@lupinum/ginko-content 0.2.1 → 0.3.0-rc.2

package/README.md

@@ -12,8 +12,8 @@ and server-side reads.
 
 ## Requirements
 
-- Node.js 20 or later
-- Nuxt 4.4.7 or later
+- Node.js 22 or later
+- Nuxt 4.4.7 through Nuxt 4.x
 - Vue 3.5 or later
 
 ## Install
@@ -113,7 +113,7 @@ For localized Nuxt apps, keep one source of truth per route type:
 
 Do not duplicate docs, blog, pricing, privacy, or translated locale paths in
 `sitemap.urls` or app-owned `nitro.prerender.routes` arrays. Use
-`@nuxtjs/sitemap >= 8.0.15` when translated static app slugs such as `/preise`
+`@nuxtjs/sitemap >= 8.0.15 < 9` when translated static app slugs such as `/preise`
 and `/en/pricing` need cross-locale sitemap alternates.
 
 See the public guide: [Sitemap and prerender](../../docs/content/docs/6.i18n/4.sitemap-prerender.md).
@@ -126,7 +126,7 @@ See the public guide: [Sitemap and prerender](../../docs/content/docs/6.i18n/4.s
 | MiniSearch backend | Included as a runtime dependency and used by the default search backend. |
 | Pagefind backend | Included as a runtime dependency and used when `content.search.engine` is `'pagefind'`. |
 | Provider-owned search | No extra package. The active content provider must advertise and implement `search`. |
-| Content i18n | Install and configure `@nuxtjs/i18n` when the app uses Nuxt locale routes. |
+| Content i18n | Install and configure `@nuxtjs/i18n` 10.x when the app uses Nuxt locale routes. |
 | Sitemap XML output | Install and configure `@nuxtjs/sitemap`; Ginko contributes the content sitemap source. |
 
 ## Scope

package/compatibility.json

@@ -1,23 +1,23 @@
 {
   "name": "Ginko Content release compatibility",
   "releaseStack": {
-    "@lupinum/ginko-content": "0.2.1",
-    "@lupinum/ginko-cms": "0.1.2",
-    "@lupinum/ginko-cms-convex": "0.1.1",
-    "@lupinum/ginko-cms-contract": "0.1.1"
+    "@lupinum/ginko-content": "0.3.0-rc.2",
+    "@lupinum/ginko-cms": "0.2.0-rc.1",
+    "@lupinum/ginko-cms-convex": "0.2.0-rc.1",
+    "@lupinum/ginko-cms-contract": "0.2.0-rc.1"
   },
   "tracked": {
-    "@convex-dev/better-auth": ["^0.12.2", "0.12.2"],
+    "@convex-dev/better-auth": ["^0.12.5", "0.12.5"],
     "@nuxtjs/mcp-toolkit": ["^0.16.1", "0.16.1"],
-    "better-auth": ["1.6.11"],
+    "better-auth": ["1.6.23"],
     "convex": ["1.38.0", "^1.38.0"],
     "convex-helpers": ["^0.1.117", "0.1.117"],
     "h3": ["1.15.11"],
-    "nuxt": ["^4.4.7", "4.4.7", ">=4.4.7"],
-    "typescript": ["~6.0.3", "^6.0.3", "6.0.3"],
-    "vite": ["^7.3.3", "7.3.3"],
-    "vitest": ["^4.1.6", ">=4.1.6"],
-    "vue-tsc": ["^3.2.9", "3.2.9"],
+    "nuxt": ["^4.4.8", "4.4.8", ">=4.4.7 <5"],
+    "typescript": ["~5.9.3", "5.9.3"],
+    "vite": ["^7.3.6", "7.3.6"],
+    "vitest": ["^4.1.10", ">=4.1.6 <5"],
+    "vue-tsc": ["^3.3.7", "3.3.7"],
     "zod": ["4.4.3", "^4.4.3"]
   },
   "intentionalHolds": [

package/dist/cli.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
 import { stat, readFile, readdir } from 'node:fs/promises';
-import { join, extname, relative } from 'node:path';
+import { join, extname, relative, resolve, isAbsolute } from 'node:path';
+import { loadNuxtConfig } from '@nuxt/kit';
+import { isContentValidationReport } from '../dist/features/validation/report.js';
 
 const ignoredDirs = /* @__PURE__ */ new Set([
   ".git",
@@ -27,7 +29,7 @@ const sourceExtensions = /* @__PURE__ */ new Set([
   ".yml",
   ".yaml"
 ]);
-const toRelativePath = (rootDir, file) => relative(rootDir, file) || ".";
+const toRelativePath = (rootDir, file) => relative(rootDir, file).replace(/\\/g, "/") || ".";
 async function collectFiles(dir, rootDir, files = []) {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -436,7 +438,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "Hardcoded locale route branch found.",
-        suggestion: "Use @nuxtjs/i18n route helpers, useContentNavigation('docs'), or useContentMany('docs', options) item paths instead of branching on locale codes."
+        suggestion: "Use @nuxtjs/i18n route helpers, navigation('docs', options), or many('docs', options) item route paths instead of branching on locale codes."
       });
     }
     if (/<(?:NuxtLink|U[A-Za-z]+)\b[^>]*:to\s*=\s*["'][^"']+\._path["']/.test(text)) {
@@ -444,7 +446,7 @@ async function inspectI18nSourceSmells(rootDir, locales) {
         severity: "error",
         file: relativeFile,
         message: "UI link is bound to raw content _path.",
-        suggestion: "Use useContentMany('docs', options) for localized list pages and bind item.path."
+        suggestion: "Use many('docs', options) from @lupinum/ginko-content/client for localized list pages and bind item.route.resolvedPath."
       });
     }
   }
@@ -505,7 +507,7 @@ async function inspectRepeatedLocalePrefixes(rootDir, locales) {
           severity: "error",
           file: relativeFile,
           message: `Repeated locale prefix "${repeatedPath}" found in generated output.`,
-          suggestion: "Bind route-ready item.path values from useContentMany(), navigation, or search results instead of manually prefixing locale paths."
+          suggestion: "Bind route-ready item.route.resolvedPath values from many(), navigation(), or search results instead of manually prefixing locale paths."
         });
         break;
       }
@@ -580,7 +582,7 @@ async function inspectI18nSearchIndex(rootDir, locales) {
           severity: "error",
           file: ".output/public/api/_content/search/index.json",
           message: `Search index has no records for locale "${locale}".`,
-          suggestion: "Use useContentSearchData() with i18n collections and verify the prerendered search payload includes every locale."
+          suggestion: "Use useContentSearch() with i18n collections and verify the prerendered search payload includes every locale."
         });
       }
     }
@@ -688,7 +690,7 @@ async function inspectSourceChecks(rootDir, checks) {
     for (const check of checks) {
       if (check.pattern.test(text)) {
         findings.push({
-          severity: "error",
+          severity: check.severity ?? "error",
           file: toRelativePath(rootDir, file),
           message: check.message,
           suggestion: check.suggestion
@@ -719,27 +721,41 @@ async function inspectPublicApiUsage(rootDir) {
     {
       pattern: /\bqueryCollectionSearchSections\s*\(/,
       message: "Nuxt Content v3 search sections helper found.",
-      suggestion: "Use useContentSearchData('docs') for UI search data."
+      suggestion: "Use useContentSearch({ collection: docs }) for UI search data."
     },
     {
       pattern: /\bqueryCollectionNavigation\s*\(/,
       message: "Nuxt Content v3 navigation helper found.",
-      suggestion: "Use useContentNavigation('docs') for layout navigation."
+      suggestion: "Use navigation('docs', options) from @lupinum/ginko-content/client inside useAsyncData for layout navigation."
     },
     {
       pattern: /\bqueryCollection\s*\(/,
       message: "Removed collection query helper found.",
-      suggestion: "Use one('docs', options), many('docs', options), paginate('docs', options), or the matching useContent* composable."
+      suggestion: "Use one('docs', options), many('docs', options), or paginate('docs', options) from @lupinum/ginko-content/client inside useAsyncData."
     },
     {
       pattern: /\buseContentList\s*\(/,
       message: "Removed content list composable found.",
-      suggestion: "Use useContentMany('docs', options) or many('docs', options)."
+      suggestion: "Use many('docs', options) from @lupinum/ginko-content/client inside useAsyncData."
     },
     {
-      pattern: /\bcontent\.(database|preview|build)\b/,
+      pattern: /\bcontent\.(database|build)\b/,
       message: "Nuxt Content v3 runtime config key found.",
-      suggestion: "Remove content.database/content.preview/content.build and configure Ginko runtime options instead."
+      suggestion: "Remove content.database/content.build and configure Ginko runtime options instead."
+    },
+    {
+      // `content.preview` is a real Ginko option (ContentPreviewOptions), unlike
+      // `content.database`/`content.build`, so it is not flagged as a v3
+      // leftover. This rule only reminds authors of its actual scope: the
+      // filesystem provider always shows drafts/partials in development, and a
+      // configured token additionally unlocks visibility for files already
+      // present in a deployed filesystem checkout. It does not fetch
+      // not-yet-published content — that kind of production preview workflow
+      // is owned by a CMS provider, not the filesystem provider.
+      pattern: /\bcontent\.preview\b/,
+      message: "content.preview configuration found.",
+      suggestion: "content.preview only gates draft/partial visibility for the filesystem provider; it always applies in development. In production it unlocks drafts already present in the deployed content directory \u2014 it is not a substitute for a provider-owned preview workflow that fetches unpublished content.",
+      severity: "info"
     },
     {
       pattern: /\.editor\s*\(/,
@@ -759,7 +775,7 @@ async function inspectRenderingUsage(rootDir) {
     {
       pattern: /<NuxtLink\b[^>]*:to\s*=\s*["'][^"']+\._path["']/,
       message: "NuxtLink is using raw content _path.",
-      suggestion: "Use useContentMany('docs', options) for list pages and bind the route-safe item.path field."
+      suggestion: "Use many('docs', options) from @lupinum/ginko-content/client for list pages and bind the route-safe item.route.resolvedPath field."
     }
   ]);
 }
@@ -834,6 +850,53 @@ async function runDoctor(options = {}) {
   };
 }
 
+const runContentValidation = async (options = {}) => {
+  const rootDir = resolve(options.rootDir || process.cwd());
+  const nuxtConfig = await loadNuxtConfig({ cwd: rootDir });
+  const buildDir = isAbsolute(nuxtConfig.buildDir) ? nuxtConfig.buildDir : resolve(rootDir, nuxtConfig.buildDir);
+  const reportPath = join(buildDir, "content-cache/validation.json");
+  let report;
+  try {
+    report = JSON.parse(await readFile(reportPath, "utf8"));
+  } catch {
+    report = void 0;
+  }
+  if (!isContentValidationReport(report)) {
+    return {
+      rootDir,
+      findings: [{
+        severity: "error",
+        file: relative(rootDir, reportPath),
+        message: "Generated content validation report not found or invalid.",
+        suggestion: "Run a Nuxt build with this Ginko Content version before `ginko-content validate`."
+      }],
+      exitCode: 1
+    };
+  }
+  return {
+    rootDir,
+    findings: report.findings,
+    exitCode: report.findings.some((finding) => finding.severity === "error") ? 1 : 0
+  };
+};
+const formatContentValidationResult = (result) => {
+  const errors = result.findings.filter((finding) => finding.severity === "error");
+  const infos = result.findings.filter((finding) => finding.severity === "info");
+  const lines = [
+    `Ginko Content validation: ${errors.length ? "issues found" : "ok"}`,
+    `Root: ${result.rootDir}`
+  ];
+  for (const [label, findings] of [["Errors", errors], ["Info", infos]]) {
+    if (!findings.length) continue;
+    lines.push("", `${label} (${findings.length})`);
+    for (const finding of findings) {
+      lines.push(`- ${finding.file}: ${finding.message}`, `  Fix: ${finding.suggestion}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+};
+
 const [, , command, ...args] = process.argv;
 if (!command || command === "--help" || command === "-h") {
   console.log([
@@ -841,16 +904,27 @@ if (!command || command === "--help" || command === "-h") {
     "",
     "Commands:",
     "  doctor [root]         Validate a Nuxt Content v3 to Ginko migration",
-    "  doctor --i18n [root]  Validate i18n migration wiring and generated output"
+    "  doctor --i18n [root]  Validate i18n migration wiring and generated output",
+    "  validate [root]       Validate internal content links, anchors, and assets"
   ].join("\n"));
   process.exit(0);
 }
-if (command !== "doctor") {
+if (command !== "doctor" && command !== "validate") {
   console.error(`Unknown command: ${command}`);
   console.error('Run "ginko-content --help" for available commands.');
   process.exit(1);
 }
 try {
+  if (command === "validate") {
+    const unknownFlag2 = args.find((arg) => arg.startsWith("-"));
+    if (unknownFlag2) {
+      console.error(`Unknown option: ${unknownFlag2}`);
+      process.exit(1);
+    }
+    const result2 = await runContentValidation({ rootDir: args[0] || process.cwd() });
+    process.stdout.write(formatContentValidationResult(result2));
+    process.exit(result2.exitCode);
+  }
   const i18n = args.includes("--i18n");
   const rootDirArg = args.find((arg) => !arg.startsWith("-"));
   const unknownFlag = args.find((arg) => arg.startsWith("-") && arg !== "--i18n");

package/dist/cms-contract/asset-bytes.d.ts

@@ -0,0 +1,10 @@
+import type { PortableMediaType } from './types.js';
+export interface VerifiedPublicImage {
+    mediaType: PortableMediaType;
+    bytes: number;
+    sha256: string;
+    width: number;
+    height: number;
+    frames: number;
+}
+export declare function verifyPublicImageBytes(source: Uint8Array | AsyncIterable<Uint8Array>, claimedMediaType?: string): Promise<VerifiedPublicImage>;

package/dist/cms-contract/asset-bytes.js

@@ -0,0 +1,266 @@
+import { IncrementalSha256 } from "./hash.js";
+import { PORTABLE_CONTENT_LIMITS } from "./limits.js";
+const {
+  assetBytes: MAX_BYTES,
+  imageDimension: MAX_DIMENSION,
+  imagePixels: MAX_PIXELS,
+  imageFrames: MAX_FRAMES,
+  imageDecodedBytes: MAX_DECODED_BYTES
+} = PORTABLE_CONTENT_LIMITS;
+const failure = (message) => {
+  throw new TypeError(`Invalid public image: ${message}`);
+};
+const u16be = (bytes, offset) => bytes[offset] << 8 | bytes[offset + 1];
+const u16le = (bytes, offset) => bytes[offset] | bytes[offset + 1] << 8;
+const u24le = (bytes, offset) => bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16;
+const u32be = (bytes, offset) => (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+const u32le = (bytes, offset) => (bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24) >>> 0;
+const ascii = (bytes, offset, length) => String.fromCharCode(...bytes.subarray(offset, offset + length));
+function validateDimensions(width, height) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width > MAX_DIMENSION || height > MAX_DIMENSION) failure("dimensions exceed the supported range.");
+  const pixels = width * height;
+  if (pixels > MAX_PIXELS) failure("pixel count exceeds the supported limit.");
+  return pixels;
+}
+function validateBounds(facts) {
+  const pixels = validateDimensions(facts.width, facts.height);
+  if (!Number.isInteger(facts.frames) || facts.frames <= 0 || facts.frames > MAX_FRAMES) {
+    failure("frame count exceeds the supported limit.");
+  }
+  if (pixels * 4 * facts.frames > MAX_DECODED_BYTES) {
+    failure("calculated decoded bytes exceed the supported limit.");
+  }
+  return facts;
+}
+let crcTable;
+function crc32(bytes) {
+  if (!crcTable) {
+    crcTable = new Uint32Array(256);
+    for (let index = 0; index < 256; index++) {
+      let value = index;
+      for (let bit = 0; bit < 8; bit++) value = value & 1 ? 3988292384 ^ value >>> 1 : value >>> 1;
+      crcTable[index] = value >>> 0;
+    }
+  }
+  let crc = 4294967295;
+  for (const byte of bytes) crc = crcTable[(crc ^ byte) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
+function parsePng(bytes) {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.length < 33 || signature.some((value, index) => bytes[index] !== value)) {
+    return failure("PNG signature is missing.");
+  }
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let frames = 1;
+  let sawHeader = false;
+  let sawData = false;
+  let sawEnd = false;
+  while (offset < bytes.length) {
+    if (offset + 12 > bytes.length) failure("PNG chunk is truncated.");
+    const length = u32be(bytes, offset);
+    const end = offset + 12 + length;
+    if (end > bytes.length) failure("PNG chunk length exceeds the file.");
+    const type = ascii(bytes, offset + 4, 4);
+    const contentEnd = offset + 8 + length;
+    if (crc32(bytes.subarray(offset + 4, contentEnd)) !== u32be(bytes, contentEnd)) {
+      failure(`PNG ${type} checksum does not match.`);
+    }
+    if (!sawHeader && type !== "IHDR") failure("PNG IHDR must be the first chunk.");
+    if (type === "IHDR") {
+      if (sawHeader || length !== 13) failure("PNG IHDR is invalid.");
+      width = u32be(bytes, offset + 8);
+      height = u32be(bytes, offset + 12);
+      if (bytes[offset + 18] !== 0 || bytes[offset + 19] !== 0 || ![0, 1].includes(bytes[offset + 20])) {
+        failure("PNG compression, filter, or interlace method is unsupported.");
+      }
+      sawHeader = true;
+    } else if (type === "IDAT") {
+      sawData = true;
+    } else if (type === "acTL") {
+      if (length !== 8) failure("PNG animation control chunk is invalid.");
+      frames = u32be(bytes, offset + 8);
+    } else if (type === "IEND") {
+      if (length !== 0 || !sawData) failure("PNG terminal chunk is invalid.");
+      sawEnd = true;
+      offset = end;
+      break;
+    }
+    offset = end;
+  }
+  if (!sawEnd || offset !== bytes.length) failure("PNG has no exact terminal IEND chunk.");
+  return validateBounds({ mediaType: "image/png", width, height, frames });
+}
+function parseJpeg(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 255 || bytes[1] !== 216) {
+    return failure("JPEG start marker is missing.");
+  }
+  let offset = 2;
+  let width = 0;
+  let height = 0;
+  let components = 0;
+  let sawEnd = false;
+  while (offset < bytes.length) {
+    if (bytes[offset++] !== 255) failure("JPEG marker prefix is invalid.");
+    while (bytes[offset] === 255) offset++;
+    const marker = bytes[offset++];
+    if (marker === void 0 || marker === 0) failure("JPEG marker is truncated.");
+    if (marker === 217) {
+      sawEnd = true;
+      break;
+    }
+    if (marker === 216 || marker >= 208 && marker <= 215 || marker === 1) continue;
+    if (offset + 2 > bytes.length) failure("JPEG segment is truncated.");
+    const length = u16be(bytes, offset);
+    if (length < 2 || offset + length > bytes.length) failure("JPEG segment length is invalid.");
+    const segmentStart = offset + 2;
+    if ([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207].includes(marker)) {
+      if (length < 8) failure("JPEG frame header is truncated.");
+      height = u16be(bytes, segmentStart + 1);
+      width = u16be(bytes, segmentStart + 3);
+      components = bytes[segmentStart + 5];
+      if (length !== 8 + components * 3) failure("JPEG frame components are malformed.");
+    }
+    offset += length;
+    if (marker === 218) {
+      while (offset < bytes.length) {
+        if (bytes[offset++] !== 255) continue;
+        while (bytes[offset] === 255) offset++;
+        const next = bytes[offset];
+        if (next === 0 || next !== void 0 && next >= 208 && next <= 215) {
+          offset++;
+          continue;
+        }
+        offset--;
+        break;
+      }
+    }
+  }
+  if (!sawEnd || offset !== bytes.length) failure("JPEG has no exact terminal EOI marker.");
+  if (!width || !height || !components) failure("JPEG frame dimensions are missing.");
+  return validateBounds({ mediaType: "image/jpeg", width, height, frames: 1 });
+}
+function skipGifSubBlocks(bytes, start) {
+  let offset = start;
+  while (true) {
+    if (offset >= bytes.length) failure("GIF sub-block stream is truncated.");
+    const length = bytes[offset++];
+    if (length === 0) return offset;
+    if (offset + length > bytes.length) failure("GIF sub-block exceeds the file.");
+    offset += length;
+  }
+}
+function parseGif(bytes) {
+  const header = ascii(bytes, 0, 6);
+  if (bytes.length < 14 || !["GIF87a", "GIF89a"].includes(header)) return failure("GIF signature is missing.");
+  const width = u16le(bytes, 6);
+  const height = u16le(bytes, 8);
+  const packed = bytes[10];
+  let offset = 13 + (packed & 128 ? 3 * (1 << (packed & 7) + 1) : 0);
+  let frames = 0;
+  let decodedPixels = 0;
+  let sawEnd = false;
+  while (offset < bytes.length) {
+    const marker = bytes[offset++];
+    if (marker === 59) {
+      sawEnd = true;
+      break;
+    }
+    if (marker === 33) {
+      if (offset >= bytes.length) failure("GIF extension is truncated.");
+      offset++;
+      offset = skipGifSubBlocks(bytes, offset);
+      continue;
+    }
+    if (marker !== 44 || offset + 9 > bytes.length) failure("GIF block marker is invalid.");
+    const frameWidth = u16le(bytes, offset + 4);
+    const frameHeight = u16le(bytes, offset + 6);
+    const framePacked = bytes[offset + 8];
+    if (!frameWidth || !frameHeight) failure("GIF frame dimensions are invalid.");
+    decodedPixels += validateDimensions(frameWidth, frameHeight);
+    if (decodedPixels * 4 > MAX_DECODED_BYTES) failure("calculated decoded bytes exceed the supported limit.");
+    offset += 9;
+    if (framePacked & 128) offset += 3 * (1 << (framePacked & 7) + 1);
+    if (offset >= bytes.length || bytes[offset++] > 11) failure("GIF LZW code size is invalid.");
+    offset = skipGifSubBlocks(bytes, offset);
+    frames++;
+  }
+  if (!sawEnd || offset !== bytes.length || frames === 0) failure("GIF has no exact terminal trailer or image frame.");
+  return validateBounds({ mediaType: "image/gif", width, height, frames });
+}
+function parseWebp(bytes) {
+  if (bytes.length < 20 || ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WEBP") {
+    return failure("WebP RIFF signature is missing.");
+  }
+  if (u32le(bytes, 4) + 8 !== bytes.length) failure("WebP RIFF length does not match the file.");
+  let offset = 12;
+  let width = 0;
+  let height = 0;
+  let frames = 0;
+  while (offset < bytes.length) {
+    if (offset + 8 > bytes.length) failure("WebP chunk is truncated.");
+    const type = ascii(bytes, offset, 4);
+    const length = u32le(bytes, offset + 4);
+    const data = offset + 8;
+    const end = data + length;
+    if (end > bytes.length) failure("WebP chunk length exceeds the file.");
+    if (type === "VP8X") {
+      if (length !== 10) failure("WebP extended header is invalid.");
+      width = u24le(bytes, data + 4) + 1;
+      height = u24le(bytes, data + 7) + 1;
+    } else if (type === "VP8 ") {
+      if (length < 10 || bytes[data + 3] !== 157 || bytes[data + 4] !== 1 || bytes[data + 5] !== 42) {
+        failure("WebP VP8 frame header is invalid.");
+      }
+      width ||= u16le(bytes, data + 6) & 16383;
+      height ||= u16le(bytes, data + 8) & 16383;
+      frames ||= 1;
+    } else if (type === "VP8L") {
+      if (length < 5 || bytes[data] !== 47) failure("WebP lossless frame header is invalid.");
+      const bits = u32le(bytes, data + 1);
+      width ||= (bits & 16383) + 1;
+      height ||= (bits >>> 14 & 16383) + 1;
+      frames ||= 1;
+    } else if (type === "ANMF") {
+      if (length < 16) failure("WebP animation frame is invalid.");
+      frames++;
+    }
+    offset = end + (length & 1);
+  }
+  if (offset !== bytes.length || !width || !height || !frames) failure("WebP container is incomplete.");
+  return validateBounds({ mediaType: "image/webp", width, height, frames });
+}
+function parseImage(bytes) {
+  if (bytes[0] === 137 && ascii(bytes, 1, 3) === "PNG") return parsePng(bytes);
+  if (bytes[0] === 255 && bytes[1] === 216) return parseJpeg(bytes);
+  if (ascii(bytes, 0, 3) === "GIF") return parseGif(bytes);
+  if (ascii(bytes, 0, 4) === "RIFF") return parseWebp(bytes);
+  return failure("signature is unsupported.");
+}
+export async function verifyPublicImageBytes(source, claimedMediaType) {
+  const hash = new IncrementalSha256();
+  const chunks = [];
+  let bytes = 0;
+  const add = (chunk) => {
+    if (!(chunk instanceof Uint8Array)) failure("byte stream contains a non-Uint8Array chunk.");
+    bytes += chunk.length;
+    if (bytes <= 0 || bytes > MAX_BYTES) failure("byte length exceeds the supported upload limit.");
+    hash.update(chunk);
+    chunks.push(chunk.slice());
+  };
+  if (source instanceof Uint8Array) add(source);
+  else for await (const chunk of source) add(chunk);
+  const all = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    all.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const facts = parseImage(all);
+  if (claimedMediaType && claimedMediaType.toLowerCase() !== facts.mediaType) {
+    failure(`claimed MIME "${claimedMediaType}" does not match verified ${facts.mediaType}.`);
+  }
+  return { ...facts, bytes, sha256: hash.digestHex() };
+}

package/dist/cms-contract/build.d.ts

@@ -1,44 +1,15 @@
-/**
- * `buildCmsContract` — deterministic normalization of a host's
- * `content.config.ts` output into the shape `@lupinum/ginko-cms` consumes.
- *
- * Per the refactor plan: the CMS used to *infer* labels, types, locales,
- * routing, and field shape from a content collection's loose config. That
- * inference produced misclassifications (data collections rendered as
- * route-backed, singletons treated as flat, fields losing media metadata).
- *
- * `buildCmsContract` instead produces a single normalized artifact. Anything
- * the CMS needs to know is recorded explicitly. The CMS is forbidden from
- * inferring on its own; it just reads this contract.
- *
- * This is a Gate 0 spike: the function is shaped end-to-end so the CMS can
- * import and call it, but the schema-introspection branches are intentionally
- * minimal. Gate 1 will fill them in against real fixtures.
- */
 import type { ContentCollectionConfig } from '../types/config.js';
-import type { CmsContract, CmsSchemaCapabilities } from './types.js';
-/** Stable contract version. Bump when the CMS-facing artifact shape changes. */
-export declare const CMS_CONTRACT_VERSION = "v1";
-export declare class CmsContractSchemaUnsupportedError extends Error {
-    readonly collectionSlug: string;
-    readonly unsupported: CmsSchemaCapabilities['unsupported'];
-    constructor(collectionSlug: string, unsupported: CmsSchemaCapabilities['unsupported']);
+import type { PortableComponentPolicyV1, ResolvedContentContractV1 } from './types.js';
+export declare const RESOLVED_CONTENT_CONTRACT_VERSION: 1;
+export interface BuildResolvedContentContractInput {
+    collections: Record<string, ContentCollectionConfig>;
 }
-export interface BuildCmsContractOptions {
-    /** Site default locale, e.g. `'en'`. */
+export interface BuildResolvedContentContractOptions {
     defaultLocale: string;
-    /** All locale codes the site can serve. */
     locales: string[];
-    /** Optional include filter — when set, only listed collections are emitted. */
+    localeFallbacks?: Record<string, string[]>;
+    translatedSlugs?: boolean;
     include?: string[];
+    componentPolicy?: PortableComponentPolicyV1;
 }
-export interface BuildCmsContractInput {
-    collections: Record<string, ContentCollectionConfig>;
-}
-/**
- * Build a normalized CMS contract from a host's `content.config.ts` output.
- *
- * The function is deterministic: same input yields byte-identical output. The
- * CMS hashes the result to detect contract changes between deployments.
- */
-export declare function buildCmsContract(config: BuildCmsContractInput, options: BuildCmsContractOptions): CmsContract;
+export declare function buildResolvedContentContract(config: BuildResolvedContentContractInput, options: BuildResolvedContentContractOptions): ResolvedContentContractV1;