vinext 0.0.0 → 0.0.2

package/dist/client/entry.js

@@ -0,0 +1,85 @@
+/**
+ * Client-side hydration entry point.
+ *
+ * This module is injected as a <script type="module"> in the SSR HTML.
+ * It reads __NEXT_DATA__ from the window, dynamically imports the page
+ * component, and hydrates it onto #__next.
+ *
+ * The actual page import path is injected at serve-time by the plugin
+ * via a virtual module or inline script.
+ */
+import React from "react";
+import { hydrateRoot } from "react-dom/client";
+// Eagerly import the router shim so its module-level popstate listener is
+// registered.  Without this, browser back/forward buttons do nothing because
+// navigateClient() is never invoked on history changes.
+import "next/router";
+// Read the SSR data injected by the server
+const nextData = window.__NEXT_DATA__;
+const { pageProps } = nextData?.props ?? { pageProps: {} };
+const pageModulePath = nextData?.__pageModule;
+const appModulePath = nextData?.__appModule;
+/** Defense-in-depth: validate module paths from __NEXT_DATA__. */
+function isValidModulePath(p) {
+    if (typeof p !== "string" || p.length === 0)
+        return false;
+    // Must start with / or ./ (relative Vite module paths)
+    if (!p.startsWith("/") && !p.startsWith("./"))
+        return false;
+    // Must not contain protocol (prevents importing from external URLs)
+    if (p.includes("://"))
+        return false;
+    // Must not traverse directories
+    if (p.includes(".."))
+        return false;
+    return true;
+}
+async function hydrate() {
+    if (!isValidModulePath(pageModulePath)) {
+        console.error("[vinext] Invalid or missing __pageModule in __NEXT_DATA__");
+        return;
+    }
+    // Dynamically import the page module
+    const pageModule = await import(/* @vite-ignore */ pageModulePath);
+    const PageComponent = pageModule.default;
+    if (!PageComponent) {
+        console.error("[vinext] Page module has no default export");
+        return;
+    }
+    let element;
+    // If there's a custom _app, wrap the page with it
+    if (appModulePath) {
+        if (!isValidModulePath(appModulePath)) {
+            console.error("[vinext] Invalid __appModule in __NEXT_DATA__");
+        }
+        else {
+            try {
+                const appModule = await import(/* @vite-ignore */ appModulePath);
+                const AppComponent = appModule.default;
+                element = React.createElement(AppComponent, {
+                    Component: PageComponent,
+                    pageProps,
+                });
+            }
+            catch {
+                // No _app, render page directly
+            }
+        }
+    }
+    // @ts-expect-error -- element is assigned in the _app branch above, or falls through here
+    if (!element) {
+        element = React.createElement(PageComponent, pageProps);
+    }
+    const container = document.getElementById("__next");
+    if (!container) {
+        console.error("[vinext] No #__next element found");
+        return;
+    }
+    const root = hydrateRoot(container, element);
+    // Expose root on window so the router shim (a separate module) can
+    // re-render the tree during client-side navigation. import.meta.hot.data
+    // is module-scoped and cannot be read across module boundaries.
+    window.__VINEXT_ROOT__ = root;
+}
+hydrate();
+//# sourceMappingURL=entry.js.map

package/dist/client/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/client/entry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Client-side hydration entry point.\n *\n * This module is injected as a <script type=\"module\"> in the SSR HTML.\n * It reads __NEXT_DATA__ from the window, dynamically imports the page\n * component, and hydrates it onto #__next.\n *\n * The actual page import path is injected at serve-time by the plugin\n * via a virtual module or inline script.\n */\nimport React from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\n// Eagerly import the router shim so its module-level popstate listener is\n// registered.  Without this, browser back/forward buttons do nothing because\n// navigateClient() is never invoked on history changes.\nimport \"next/router\";\n\n// Read the SSR data injected by the server\nconst nextData = (window as any).__NEXT_DATA__;\nconst { pageProps } = nextData?.props ?? { pageProps: {} };\nconst pageModulePath = nextData?.__pageModule;\nconst appModulePath = nextData?.__appModule;\n\n/** Defense-in-depth: validate module paths from __NEXT_DATA__. */\nfunction isValidModulePath(p: unknown): p is string {\n  if (typeof p !== \"string\" || p.length === 0) return false;\n  // Must start with / or ./ (relative Vite module paths)\n  if (!p.startsWith(\"/\") && !p.startsWith(\"./\")) return false;\n  // Must not contain protocol (prevents importing from external URLs)\n  if (p.includes(\"://\")) return false;\n  // Must not traverse directories\n  if (p.includes(\"..\")) return false;\n  return true;\n}\n\nasync function hydrate() {\n  if (!isValidModulePath(pageModulePath)) {\n    console.error(\"[vinext] Invalid or missing __pageModule in __NEXT_DATA__\");\n    return;\n  }\n\n  // Dynamically import the page module\n  const pageModule = await import(/* @vite-ignore */ pageModulePath);\n  const PageComponent = pageModule.default;\n\n  if (!PageComponent) {\n    console.error(\"[vinext] Page module has no default export\");\n    return;\n  }\n\n  let element: React.ReactElement;\n\n  // If there's a custom _app, wrap the page with it\n  if (appModulePath) {\n    if (!isValidModulePath(appModulePath)) {\n      console.error(\"[vinext] Invalid __appModule in __NEXT_DATA__\");\n    } else {\n      try {\n        const appModule = await import(/* @vite-ignore */ appModulePath);\n        const AppComponent = appModule.default;\n        element = React.createElement(AppComponent, {\n          Component: PageComponent,\n          pageProps,\n        });\n      } catch {\n        // No _app, render page directly\n      }\n    }\n  }\n\n  // @ts-expect-error -- element is assigned in the _app branch above, or falls through here\n  if (!element) {\n    element = React.createElement(PageComponent, pageProps);\n  }\n\n  const container = document.getElementById(\"__next\");\n  if (!container) {\n    console.error(\"[vinext] No #__next element found\");\n    return;\n  }\n\n  const root = hydrateRoot(container, element);\n\n  // Expose root on window so the router shim (a separate module) can\n  // re-render the tree during client-side navigation. import.meta.hot.data\n  // is module-scoped and cannot be read across module boundaries.\n  (window as any).__VINEXT_ROOT__ = root;\n}\n\nhydrate();\n"]}

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vinext/cloudflare — Cloudflare Workers integration.
+ *
+ * Provides cache handlers and utilities for running vinext on Cloudflare Workers.
+ */
+export { KVCacheHandler } from "./kv-cache-handler.js";
+export { runTPR, type TPROptions, type TPRResult } from "./tpr.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cloudflare/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cloudflare/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/cloudflare/index.js

@@ -0,0 +1,8 @@
+/**
+ * vinext/cloudflare — Cloudflare Workers integration.
+ *
+ * Provides cache handlers and utilities for running vinext on Cloudflare Workers.
+ */
+export { KVCacheHandler } from "./kv-cache-handler.js";
+export { runTPR } from "./tpr.js";
+//# sourceMappingURL=index.js.map

package/dist/cloudflare/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cloudflare/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAmC,MAAM,UAAU,CAAC","sourcesContent":["/**\n * vinext/cloudflare — Cloudflare Workers integration.\n *\n * Provides cache handlers and utilities for running vinext on Cloudflare Workers.\n */\n\nexport { KVCacheHandler } from \"./kv-cache-handler.js\";\nexport { runTPR, type TPROptions, type TPRResult } from \"./tpr.js\";\n"]}

package/dist/cloudflare/kv-cache-handler.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cloudflare KV-backed CacheHandler for vinext.
+ *
+ * Provides persistent ISR caching on Cloudflare Workers using KV as the
+ * storage backend. Supports time-based expiry (stale-while-revalidate)
+ * and tag-based invalidation.
+ *
+ * Usage in worker/index.ts:
+ *
+ *   import { KVCacheHandler } from "vinext/cloudflare";
+ *   import { setCacheHandler } from "vinext/shims/cache";
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));
+ *       // ... rest of worker handler
+ *     }
+ *   };
+ *
+ * Wrangler config (wrangler.jsonc):
+ *
+ *   {
+ *     "kv_namespaces": [
+ *       { "binding": "VINEXT_CACHE", "id": "<your-kv-namespace-id>" }
+ *     ]
+ *   }
+ */
+import type { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../shims/cache.js";
+interface KVNamespace {
+    get(key: string, options?: {
+        type?: string;
+    }): Promise<string | null>;
+    get(key: string, options: {
+        type: "arrayBuffer";
+    }): Promise<ArrayBuffer | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
+        expirationTtl?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+            metadata?: Record<string, unknown>;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+export declare class KVCacheHandler implements CacheHandler {
+    private kv;
+    private prefix;
+    constructor(kvNamespace: KVNamespace, options?: {
+        appPrefix?: string;
+    });
+    get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+    set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+    revalidateTag(tags: string | string[], _durations?: {
+        expire?: number;
+    }): Promise<void>;
+    resetRequestCache(): void;
+}
+export {};
+//# sourceMappingURL=kv-cache-handler.d.ts.map

package/dist/cloudflare/kv-cache-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-cache-handler.d.ts","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAG3B,UAAU,WAAW;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAChF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,cAAc,EAC5C,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QACV,IAAI,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAC;QAClE,aAAa,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAiCD,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKhE,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkE9B,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,GAAG,IAAI,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IA8DV,aAAa,CACjB,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,IAAI,CAAC;IAehB,iBAAiB,IAAI,IAAI;CAG1B"}

package/dist/cloudflare/kv-cache-handler.js

@@ -0,0 +1,304 @@
+/**
+ * Cloudflare KV-backed CacheHandler for vinext.
+ *
+ * Provides persistent ISR caching on Cloudflare Workers using KV as the
+ * storage backend. Supports time-based expiry (stale-while-revalidate)
+ * and tag-based invalidation.
+ *
+ * Usage in worker/index.ts:
+ *
+ *   import { KVCacheHandler } from "vinext/cloudflare";
+ *   import { setCacheHandler } from "vinext/shims/cache";
+ *
+ *   export default {
+ *     async fetch(request: Request, env: Env) {
+ *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));
+ *       // ... rest of worker handler
+ *     }
+ *   };
+ *
+ * Wrangler config (wrangler.jsonc):
+ *
+ *   {
+ *     "kv_namespaces": [
+ *       { "binding": "VINEXT_CACHE", "id": "<your-kv-namespace-id>" }
+ *     ]
+ *   }
+ */
+/** Key prefix for tag invalidation timestamps. */
+const TAG_PREFIX = "__tag:";
+/** Key prefix for cache entries. */
+const ENTRY_PREFIX = "cache:";
+/** Max tag length to prevent KV key abuse. */
+const MAX_TAG_LENGTH = 256;
+/**
+ * Validate a cache tag. Returns null if invalid.
+ * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a
+ * separator — allowing `:` in user tags could cause ambiguous key lookups.
+ */
+function validateTag(tag) {
+    if (typeof tag !== "string" || tag.length === 0 || tag.length > MAX_TAG_LENGTH)
+        return null;
+    // Block control characters, path separators, and KV-special characters.
+    // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags
+    if (/[\x00-\x1f/\\:]/.test(tag))
+        return null;
+    return tag;
+}
+export class KVCacheHandler {
+    kv;
+    prefix;
+    constructor(kvNamespace, options) {
+        this.kv = kvNamespace;
+        this.prefix = options?.appPrefix ? `${options.appPrefix}:` : "";
+    }
+    async get(key, _ctx) {
+        const kvKey = this.prefix + ENTRY_PREFIX + key;
+        const raw = await this.kv.get(kvKey);
+        if (!raw)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Corrupted JSON — delete and treat as miss
+            await this.kv.delete(kvKey);
+            return null;
+        }
+        // Validate deserialized shape before using
+        const entry = validateCacheEntry(parsed);
+        if (!entry) {
+            console.error("[vinext] Invalid cache entry shape for key:", key);
+            await this.kv.delete(kvKey);
+            return null;
+        }
+        // Restore ArrayBuffer fields that were base64-encoded for JSON storage
+        if (entry.value) {
+            const ok = restoreArrayBuffers(entry.value);
+            if (!ok) {
+                // base64 decode failed — corrupted entry, treat as miss
+                await this.kv.delete(kvKey);
+                return null;
+            }
+        }
+        // Check tag-based invalidation (parallel for lower latency)
+        if (entry.tags.length > 0) {
+            const tagResults = await Promise.all(entry.tags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)));
+            for (let i = 0; i < entry.tags.length; i++) {
+                const tagTime = tagResults[i];
+                if (tagTime) {
+                    const tagTimestamp = Number(tagTime);
+                    if (Number.isNaN(tagTimestamp) || tagTimestamp >= entry.lastModified) {
+                        // Tag was invalidated after this entry, or timestamp is corrupted
+                        // — treat as miss to force re-render
+                        await this.kv.delete(kvKey);
+                        return null;
+                    }
+                }
+            }
+        }
+        // Check time-based expiry — return stale with cacheState
+        if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) {
+            return {
+                lastModified: entry.lastModified,
+                value: entry.value,
+                cacheState: "stale",
+            };
+        }
+        return {
+            lastModified: entry.lastModified,
+            value: entry.value,
+        };
+    }
+    async set(key, data, ctx) {
+        // Collect, validate, and dedupe tags from data and context
+        const tagSet = new Set();
+        if (data && "tags" in data && Array.isArray(data.tags)) {
+            for (const t of data.tags) {
+                const validated = validateTag(t);
+                if (validated)
+                    tagSet.add(validated);
+            }
+        }
+        if (ctx && "tags" in ctx && Array.isArray(ctx.tags)) {
+            for (const t of ctx.tags) {
+                const validated = validateTag(t);
+                if (validated)
+                    tagSet.add(validated);
+            }
+        }
+        const tags = [...tagSet];
+        // Determine revalidation time
+        let revalidateAt = null;
+        if (ctx) {
+            const revalidate = ctx.cacheControl?.revalidate ?? ctx.revalidate;
+            if (typeof revalidate === "number" && revalidate > 0) {
+                revalidateAt = Date.now() + revalidate * 1000;
+            }
+        }
+        if (data &&
+            "revalidate" in data &&
+            typeof data.revalidate === "number" &&
+            data.revalidate > 0) {
+            revalidateAt = Date.now() + data.revalidate * 1000;
+        }
+        // Prepare entry — convert ArrayBuffers to base64 for JSON storage
+        const serializable = data ? serializeForJSON(data) : null;
+        const entry = {
+            value: serializable,
+            tags,
+            lastModified: Date.now(),
+            revalidateAt,
+        };
+        // Calculate KV TTL — keep entries well beyond their revalidate window
+        // (10x revalidate period, clamped to 60s–30d) so stale-while-revalidate
+        // can serve stale content while background regeneration happens.
+        let expirationTtl;
+        if (revalidateAt !== null) {
+            const revalidateSeconds = Math.ceil((revalidateAt - Date.now()) / 1000);
+            // Keep in KV for 10x the revalidation period, up to 30 days
+            expirationTtl = Math.min(revalidateSeconds * 10, 30 * 24 * 3600);
+            // KV minimum TTL is 60 seconds
+            expirationTtl = Math.max(expirationTtl, 60);
+        }
+        await this.kv.put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {
+            expirationTtl,
+        });
+    }
+    async revalidateTag(tags, _durations) {
+        const tagList = Array.isArray(tags) ? tags : [tags];
+        const now = Date.now();
+        const validTags = tagList.filter((t) => validateTag(t) !== null);
+        // Store invalidation timestamp for each tag
+        // Use a long TTL (30 days) so recent invalidations are always found
+        await Promise.all(validTags.map((tag) => this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {
+            expirationTtl: 30 * 24 * 3600,
+        })));
+    }
+    resetRequestCache() {
+        // No-op — KV is stateless per request
+    }
+}
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const VALID_KINDS = new Set([
+    "FETCH",
+    "APP_PAGE",
+    "PAGES",
+    "APP_ROUTE",
+    "REDIRECT",
+    "IMAGE",
+]);
+/**
+ * Validate that a parsed JSON value has the expected KVCacheEntry shape.
+ * Returns the validated entry or null if the shape is invalid.
+ */
+function validateCacheEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    // Required fields
+    if (typeof obj.lastModified !== "number")
+        return null;
+    if (!Array.isArray(obj.tags))
+        return null;
+    if (obj.revalidateAt !== null &&
+        typeof obj.revalidateAt !== "number")
+        return null;
+    // value must be null or a valid cache value object with a known kind
+    if (obj.value !== null) {
+        if (!obj.value || typeof obj.value !== "object")
+            return null;
+        const value = obj.value;
+        if (typeof value.kind !== "string" || !VALID_KINDS.has(value.kind))
+            return null;
+    }
+    return raw;
+}
+// ---------------------------------------------------------------------------
+// ArrayBuffer serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Deep-clone a cache value, converting ArrayBuffer fields to base64 strings
+ * so the entire structure can be JSON.stringify'd for KV storage.
+ */
+function serializeForJSON(value) {
+    if (value.kind === "APP_PAGE") {
+        return {
+            ...value,
+            rscData: value.rscData
+                ? arrayBufferToBase64(value.rscData)
+                : undefined,
+        };
+    }
+    if (value.kind === "APP_ROUTE") {
+        return {
+            ...value,
+            body: arrayBufferToBase64(value.body),
+        };
+    }
+    if (value.kind === "IMAGE") {
+        return {
+            ...value,
+            buffer: arrayBufferToBase64(value.buffer),
+        };
+    }
+    return value;
+}
+/**
+ * Restore base64 strings back to ArrayBuffers after JSON.parse.
+ * Returns false if any base64 decode fails (corrupted entry).
+ */
+function restoreArrayBuffers(value) {
+    if (value.kind === "APP_PAGE" && typeof value.rscData === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.rscData);
+        if (!decoded)
+            return false;
+        value.rscData = decoded;
+    }
+    if (value.kind === "APP_ROUTE" && typeof value.body === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.body);
+        if (!decoded)
+            return false;
+        value.body = decoded;
+    }
+    if (value.kind === "IMAGE" && typeof value.buffer === "string") {
+        const decoded = safeBase64ToArrayBuffer(value.buffer);
+        if (!decoded)
+            return false;
+        value.buffer = decoded;
+    }
+    return true;
+}
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64ToArrayBuffer(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+/**
+ * Safely decode base64 to ArrayBuffer. Returns null on invalid input
+ * instead of throwing a DOMException.
+ */
+function safeBase64ToArrayBuffer(base64) {
+    try {
+        return base64ToArrayBuffer(base64);
+    }
+    catch {
+        console.error("[vinext] Invalid base64 in cache entry");
+        return null;
+    }
+}
+//# sourceMappingURL=kv-cache-handler.js.map

package/dist/cloudflare/kv-cache-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-cache-handler.js","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cloudflare KV-backed CacheHandler for vinext.\n *\n * Provides persistent ISR caching on Cloudflare Workers using KV as the\n * storage backend. Supports time-based expiry (stale-while-revalidate)\n * and tag-based invalidation.\n *\n * Usage in worker/index.ts:\n *\n *   import { KVCacheHandler } from \"vinext/cloudflare\";\n *   import { setCacheHandler } from \"vinext/shims/cache\";\n *\n *   export default {\n *     async fetch(request: Request, env: Env) {\n *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));\n *       // ... rest of worker handler\n *     }\n *   };\n *\n * Wrangler config (wrangler.jsonc):\n *\n *   {\n *     \"kv_namespaces\": [\n *       { \"binding\": \"VINEXT_CACHE\", \"id\": \"<your-kv-namespace-id>\" }\n *     ]\n *   }\n */\n\nimport type {\n  CacheHandler,\n  CacheHandlerValue,\n  IncrementalCacheValue,\n} from \"../shims/cache.js\";\n\n// Cloudflare KV namespace interface (matches Workers types)\ninterface KVNamespace {\n  get(key: string, options?: { type?: string }): Promise<string | null>;\n  get(key: string, options: { type: \"arrayBuffer\" }): Promise<ArrayBuffer | null>;\n  put(\n    key: string,\n    value: string | ArrayBuffer | ReadableStream,\n    options?: { expirationTtl?: number; metadata?: Record<string, unknown> },\n  ): Promise<void>;\n  delete(key: string): Promise<void>;\n  list(options?: {\n    prefix?: string;\n    limit?: number;\n    cursor?: string;\n  }): Promise<{\n    keys: Array<{ name: string; metadata?: Record<string, unknown> }>;\n    list_complete: boolean;\n    cursor?: string;\n  }>;\n}\n\n/** Shape stored in KV for each cache entry. */\ninterface KVCacheEntry {\n  value: IncrementalCacheValue | null;\n  tags: string[];\n  lastModified: number;\n  /** Absolute timestamp (ms) after which the entry is \"stale\" (but still served). */\n  revalidateAt: number | null;\n}\n\n/** Key prefix for tag invalidation timestamps. */\nconst TAG_PREFIX = \"__tag:\";\n\n/** Key prefix for cache entries. */\nconst ENTRY_PREFIX = \"cache:\";\n\n/** Max tag length to prevent KV key abuse. */\nconst MAX_TAG_LENGTH = 256;\n\n/**\n * Validate a cache tag. Returns null if invalid.\n * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a\n * separator — allowing `:` in user tags could cause ambiguous key lookups.\n */\nfunction validateTag(tag: string): string | null {\n  if (typeof tag !== \"string\" || tag.length === 0 || tag.length > MAX_TAG_LENGTH) return null;\n  // Block control characters, path separators, and KV-special characters.\n  // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags\n  if (/[\\x00-\\x1f/\\\\:]/.test(tag)) return null;\n  return tag;\n}\n\nexport class KVCacheHandler implements CacheHandler {\n  private kv: KVNamespace;\n  private prefix: string;\n\n  constructor(kvNamespace: KVNamespace, options?: { appPrefix?: string }) {\n    this.kv = kvNamespace;\n    this.prefix = options?.appPrefix ? `${options.appPrefix}:` : \"\";\n  }\n\n  async get(\n    key: string,\n    _ctx?: Record<string, unknown>,\n  ): Promise<CacheHandlerValue | null> {\n    const kvKey = this.prefix + ENTRY_PREFIX + key;\n    const raw = await this.kv.get(kvKey);\n    if (!raw) return null;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Corrupted JSON — delete and treat as miss\n      await this.kv.delete(kvKey);\n      return null;\n    }\n\n    // Validate deserialized shape before using\n    const entry = validateCacheEntry(parsed);\n    if (!entry) {\n      console.error(\"[vinext] Invalid cache entry shape for key:\", key);\n      await this.kv.delete(kvKey);\n      return null;\n    }\n\n    // Restore ArrayBuffer fields that were base64-encoded for JSON storage\n    if (entry.value) {\n      const ok = restoreArrayBuffers(entry.value);\n      if (!ok) {\n        // base64 decode failed — corrupted entry, treat as miss\n        await this.kv.delete(kvKey);\n        return null;\n      }\n    }\n\n    // Check tag-based invalidation (parallel for lower latency)\n    if (entry.tags.length > 0) {\n      const tagResults = await Promise.all(\n        entry.tags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)),\n      );\n      for (let i = 0; i < entry.tags.length; i++) {\n        const tagTime = tagResults[i];\n        if (tagTime) {\n          const tagTimestamp = Number(tagTime);\n          if (Number.isNaN(tagTimestamp) || tagTimestamp >= entry.lastModified) {\n            // Tag was invalidated after this entry, or timestamp is corrupted\n            // — treat as miss to force re-render\n            await this.kv.delete(kvKey);\n            return null;\n          }\n        }\n      }\n    }\n\n    // Check time-based expiry — return stale with cacheState\n    if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) {\n      return {\n        lastModified: entry.lastModified,\n        value: entry.value,\n        cacheState: \"stale\",\n      };\n    }\n\n    return {\n      lastModified: entry.lastModified,\n      value: entry.value,\n    };\n  }\n\n  async set(\n    key: string,\n    data: IncrementalCacheValue | null,\n    ctx?: Record<string, unknown>,\n  ): Promise<void> {\n    // Collect, validate, and dedupe tags from data and context\n    const tagSet = new Set<string>();\n    if (data && \"tags\" in data && Array.isArray(data.tags)) {\n      for (const t of data.tags) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    if (ctx && \"tags\" in ctx && Array.isArray(ctx.tags)) {\n      for (const t of ctx.tags as string[]) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    const tags = [...tagSet];\n\n    // Determine revalidation time\n    let revalidateAt: number | null = null;\n    if (ctx) {\n      const revalidate =\n        (ctx as any).cacheControl?.revalidate ?? (ctx as any).revalidate;\n      if (typeof revalidate === \"number\" && revalidate > 0) {\n        revalidateAt = Date.now() + revalidate * 1000;\n      }\n    }\n    if (\n      data &&\n      \"revalidate\" in data &&\n      typeof data.revalidate === \"number\" &&\n      data.revalidate > 0\n    ) {\n      revalidateAt = Date.now() + data.revalidate * 1000;\n    }\n\n    // Prepare entry — convert ArrayBuffers to base64 for JSON storage\n    const serializable = data ? serializeForJSON(data) : null;\n\n    const entry: KVCacheEntry = {\n      value: serializable,\n      tags,\n      lastModified: Date.now(),\n      revalidateAt,\n    };\n\n    // Calculate KV TTL — keep entries well beyond their revalidate window\n    // (10x revalidate period, clamped to 60s–30d) so stale-while-revalidate\n    // can serve stale content while background regeneration happens.\n    let expirationTtl: number | undefined;\n    if (revalidateAt !== null) {\n      const revalidateSeconds = Math.ceil((revalidateAt - Date.now()) / 1000);\n      // Keep in KV for 10x the revalidation period, up to 30 days\n      expirationTtl = Math.min(revalidateSeconds * 10, 30 * 24 * 3600);\n      // KV minimum TTL is 60 seconds\n      expirationTtl = Math.max(expirationTtl, 60);\n    }\n\n    await this.kv.put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {\n      expirationTtl,\n    });\n  }\n\n  async revalidateTag(\n    tags: string | string[],\n    _durations?: { expire?: number },\n  ): Promise<void> {\n    const tagList = Array.isArray(tags) ? tags : [tags];\n    const now = Date.now();\n    const validTags = tagList.filter((t) => validateTag(t) !== null);\n    // Store invalidation timestamp for each tag\n    // Use a long TTL (30 days) so recent invalidations are always found\n    await Promise.all(\n      validTags.map((tag) =>\n        this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {\n          expirationTtl: 30 * 24 * 3600,\n        }),\n      ),\n    );\n  }\n\n  resetRequestCache(): void {\n    // No-op — KV is stateless per request\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation helpers\n// ---------------------------------------------------------------------------\n\nconst VALID_KINDS = new Set([\n  \"FETCH\",\n  \"APP_PAGE\",\n  \"PAGES\",\n  \"APP_ROUTE\",\n  \"REDIRECT\",\n  \"IMAGE\",\n]);\n\n/**\n * Validate that a parsed JSON value has the expected KVCacheEntry shape.\n * Returns the validated entry or null if the shape is invalid.\n */\nfunction validateCacheEntry(raw: unknown): KVCacheEntry | null {\n  if (!raw || typeof raw !== \"object\") return null;\n\n  const obj = raw as Record<string, unknown>;\n\n  // Required fields\n  if (typeof obj.lastModified !== \"number\") return null;\n  if (!Array.isArray(obj.tags)) return null;\n  if (\n    obj.revalidateAt !== null &&\n    typeof obj.revalidateAt !== \"number\"\n  )\n    return null;\n\n  // value must be null or a valid cache value object with a known kind\n  if (obj.value !== null) {\n    if (!obj.value || typeof obj.value !== \"object\") return null;\n    const value = obj.value as Record<string, unknown>;\n    if (typeof value.kind !== \"string\" || !VALID_KINDS.has(value.kind))\n      return null;\n  }\n\n  return raw as KVCacheEntry;\n}\n\n// ---------------------------------------------------------------------------\n// ArrayBuffer serialization helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Deep-clone a cache value, converting ArrayBuffer fields to base64 strings\n * so the entire structure can be JSON.stringify'd for KV storage.\n */\nfunction serializeForJSON(value: IncrementalCacheValue): IncrementalCacheValue {\n  if (value.kind === \"APP_PAGE\") {\n    return {\n      ...value,\n      rscData: value.rscData\n        ? (arrayBufferToBase64(value.rscData) as any)\n        : undefined,\n    };\n  }\n  if (value.kind === \"APP_ROUTE\") {\n    return {\n      ...value,\n      body: arrayBufferToBase64(value.body) as any,\n    };\n  }\n  if (value.kind === \"IMAGE\") {\n    return {\n      ...value,\n      buffer: arrayBufferToBase64(value.buffer) as any,\n    };\n  }\n  return value;\n}\n\n/**\n * Restore base64 strings back to ArrayBuffers after JSON.parse.\n * Returns false if any base64 decode fails (corrupted entry).\n */\nfunction restoreArrayBuffers(value: IncrementalCacheValue): boolean {\n  if (value.kind === \"APP_PAGE\" && typeof value.rscData === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.rscData as any);\n    if (!decoded) return false;\n    (value as any).rscData = decoded;\n  }\n  if (value.kind === \"APP_ROUTE\" && typeof value.body === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.body as any);\n    if (!decoded) return false;\n    (value as any).body = decoded;\n  }\n  if (value.kind === \"IMAGE\" && typeof value.buffer === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.buffer as any);\n    if (!decoded) return false;\n    (value as any).buffer = decoded;\n  }\n  return true;\n}\n\nfunction arrayBufferToBase64(buffer: ArrayBuffer): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\nfunction base64ToArrayBuffer(base64: string): ArrayBuffer {\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes.buffer;\n}\n\n/**\n * Safely decode base64 to ArrayBuffer. Returns null on invalid input\n * instead of throwing a DOMException.\n */\nfunction safeBase64ToArrayBuffer(base64: string): ArrayBuffer | null {\n  try {\n    return base64ToArrayBuffer(base64);\n  } catch {\n    console.error(\"[vinext] Invalid base64 in cache entry\");\n    return null;\n  }\n}\n"]}

package/dist/cloudflare/tpr.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TPR: Traffic-aware Pre-Rendering
+ *
+ * Uses Cloudflare zone analytics to determine which pages actually get
+ * traffic, and pre-renders only those during deploy. The pre-rendered
+ * HTML is uploaded to KV in the same format ISR uses at runtime — no
+ * runtime changes needed.
+ *
+ * Flow:
+ *   1. Parse wrangler config to find custom domain and KV namespace
+ *   2. Resolve the Cloudflare zone for the custom domain
+ *   3. Query zone analytics (GraphQL) for top pages by request count
+ *   4. Walk ranked list until coverage threshold is met
+ *   5. Start the built production server locally
+ *   6. Fetch each hot route to produce HTML
+ *   7. Upload pre-rendered HTML to KV (same KVCacheEntry format ISR reads)
+ *
+ * TPR is an experimental feature enabled via --experimental-tpr. It
+ * gracefully skips when no custom domain, no API token, no traffic data,
+ * or no KV namespace is configured.
+ */
+export interface TPROptions {
+    /** Project root directory. */
+    root: string;
+    /** Traffic coverage percentage (0–100). Default: 90. */
+    coverage: number;
+    /** Hard cap on number of pages to pre-render. Default: 1000. */
+    limit: number;
+    /** Analytics lookback window in hours. Default: 24. */
+    window: number;
+}
+export interface TPRResult {
+    /** Total unique page paths found in analytics. */
+    totalPaths: number;
+    /** Number of pages successfully pre-rendered and uploaded. */
+    prerenderedCount: number;
+    /** Actual traffic coverage achieved (percentage). */
+    coverageAchieved: number;
+    /** Wall-clock duration of the TPR step in milliseconds. */
+    durationMs: number;
+    /** If TPR was skipped, the reason. */
+    skipped?: string;
+}
+interface TrafficEntry {
+    path: string;
+    requests: number;
+}
+interface SelectedRoutes {
+    routes: TrafficEntry[];
+    totalRequests: number;
+    coveredRequests: number;
+    coveragePercent: number;
+}
+interface WranglerConfig {
+    accountId?: string;
+    kvNamespaceId?: string;
+    customDomain?: string;
+}
+/**
+ * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
+ * account_id, VINEXT_CACHE KV namespace ID, and custom domain.
+ */
+export declare function parseWranglerConfig(root: string): WranglerConfig | null;
+/**
+ * Walk the ranked traffic list, accumulating request counts until the
+ * coverage target is met or the hard cap is reached.
+ */
+export declare function selectRoutes(traffic: TrafficEntry[], coverageTarget: number, limit: number): SelectedRoutes;
+/**
+ * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
+ *
+ * Designed to be called between the build step and wrangler deploy in
+ * the `vinext deploy` pipeline. Gracefully skips (never errors) when
+ * the prerequisites aren't met.
+ */
+export declare function runTPR(options: TPROptions): Promise<TPRResult>;
+export {};
+//# sourceMappingURL=tpr.d.ts.map

package/dist/cloudflare/tpr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tpr.d.ts","sourceRoot":"","sources":["../../src/cloudflare/tpr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBvE;AAkXD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,CAuBhB;AAyPD;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAmIpE"}