fix: percent-encode X-Vinext-Params to allow non-ASCII route params (#677)

Headers.set() requires ByteString values (chars <= U+00FF). When dynamic
route params contain non-ASCII characters (Korean, Japanese, etc.),
JSON.stringify preserves them verbatim which causes a TypeError on the
Headers.set() call in buildAppPageRscResponse.

Fix: encodeURIComponent the JSON on the server side before setting the
header, and decodeURIComponent on the client side when reading it back
during initial hydration and client-side navigation.

Closes #676

Author: southpolesteve

packages/vinext/src/server/app-browser-entry.ts

@@ -104,7 +104,7 @@ async function readInitialRscStream(): Promise<ReadableStream<Uint8Array>> {
   const paramsHeader = rscResponse.headers.get("X-Vinext-Params");
   if (paramsHeader) {
     try {
-      params = JSON.parse(paramsHeader) as Record<string, string | string[]>;
+      params = JSON.parse(decodeURIComponent(paramsHeader)) as Record<string, string | string[]>;
       setClientParams(params);
     } catch {
       // Ignore malformed param headers and continue with hydration.
@@ -243,7 +243,7 @@ async function main(): Promise<void> {
       const paramsHeader = navResponse.headers.get("X-Vinext-Params");
       if (paramsHeader) {
         try {
-          setClientParams(JSON.parse(paramsHeader));
+          setClientParams(JSON.parse(decodeURIComponent(paramsHeader)));
         } catch {
           setClientParams({});
         }

packages/vinext/src/server/app-page-response.ts

@@ -167,7 +167,9 @@ export function buildAppPageRscResponse(
   });
 
   if (options.params && Object.keys(options.params).length > 0) {
-    headers.set("X-Vinext-Params", JSON.stringify(options.params));
+    // encodeURIComponent so non-ASCII params (e.g. Korean slugs) survive the
+    // HTTP ByteString constraint — Headers.set() rejects chars above U+00FF.
+    headers.set("X-Vinext-Params", encodeURIComponent(JSON.stringify(options.params)));
   }
   if (options.policy.cacheControl) {
     headers.set("Cache-Control", options.policy.cacheControl);

tests/app-page-response.test.ts

@@ -220,14 +220,34 @@ describe("app page response helpers", () => {
 
     expect(response.status).toBe(202);
     expect(response.headers.get("content-type")).toBe("text/x-component; charset=utf-8");
-    expect(response.headers.get("x-vinext-params")).toBe('{"slug":"test"}');
+    expect(response.headers.get("x-vinext-params")).toBe(encodeURIComponent('{"slug":"test"}'));
     expect(response.headers.get("cache-control")).toBe("private, max-age=5");
     expect(response.headers.get("x-vinext-cache")).toBe("MISS");
     expect(response.headers.get("vary")).toBe("RSC, Accept, Next-Router-State-Tree");
     expect(response.headers.get("x-vinext-timing")).toBe("10,5,-1");
     await expect(response.text()).resolves.toBe("flight");
   });
 
+  it("percent-encodes X-Vinext-Params so non-ASCII characters survive the ByteString header constraint (issue #676)", () => {
+    // HTTP headers are ByteStrings: each character value must be <= 255.
+    // JSON.stringify preserves non-ASCII characters verbatim (e.g. Korean 완 = U+C644 = 50756),
+    // which causes Headers.set() to throw a TypeError in compliant runtimes.
+    // The fix: encodeURIComponent the JSON before setting the header.
+    const koreanSlug = "useState-완전정복";
+    const response = buildAppPageRscResponse(createBody("flight"), {
+      middlewareContext: { headers: new Headers(), status: 200 },
+      params: { slug: [koreanSlug] },
+      policy: {},
+      timing: { handlerStart: 0, responseKind: "rsc" },
+    });
+
+    const rawHeader = response.headers.get("x-vinext-params")!;
+    // Header value must be ASCII-safe (all byte values <= 127 after encoding)
+    expect(Array.from(rawHeader).every((c) => c.charCodeAt(0) <= 127)).toBe(true);
+    // Decoding must round-trip back to the original params
+    expect(JSON.parse(decodeURIComponent(rawHeader))).toEqual({ slug: [koreanSlug] });
+  });
+
   it("builds HTML responses with draft cookies, preload links, middleware, and timing", async () => {
     const middlewareHeaders = new Headers();
     middlewareHeaders.append("set-cookie", "mw=1; Path=/");