ruact 0.0.3 → 0.0.4

data/vendor/javascript/ruact-server-functions-runtime/index.js

@@ -16,6 +16,13 @@
 // import path are part of the locked API — do NOT change without coordinated
 // codegen + Vite-plugin updates.
 
+// Story 9.5 — `useQuery` is a React hook, so the runtime now depends on React.
+// React is declared as a `peerDependency` (every host already has it; the
+// runtime never bundles its own copy). This is the runtime's first React
+// import — the mutation path (`_makeRef` / `_makeServerFunction`) stays
+// React-free.
+import { useState, useEffect } from "react";
+
 const RUNTIME_VERSION = 1;
 
 // Re-run-5 (2026-05-15) — module-level runtime configuration. Hosts
@@ -149,6 +156,91 @@ export function _makeServerFunction(descriptor) {
   };
 }
 
+/**
+ * Story 9.5 — the read-side (query) accessor. The codegen emits
+ * `_makeQuery({ path, kind: "query" })` for every method on a mounted
+ * `Ruact::Query` subclass. The returned callable issues a **GET** to the
+ * named query route (`GET /q/<jsId>`), serializing `params` into the query
+ * string.
+ *
+ * Reads are CSRF-free (NFR27 / the 2026-06-02 ADR addendum voids the old
+ * `POST /__ruact/fn/:id` query mechanism and restores HTTP GET semantics):
+ * no request body, no `X-CSRF-Token`. It shares `parseResponse` /
+ * `RuactActionError` / `redirect: "error"` with the mutation path so the
+ * success + failure shapes are identical.
+ *
+ * Usually consumed through {useQuery}, but the returned function is a plain
+ * `(params?) => Promise<unknown>` so it also works in imperative code.
+ *
+ * FR88 wire format: only primitives (string / number / boolean / null) are
+ * encoded into the query string; arrays and objects throw a `TypeError`
+ * client-side too — though the server-side sanitization is authoritative.
+ *
+ * @param {{ path: string, kind?: string }} descriptor
+ * @returns {(params?: Record<string, unknown>) => Promise<unknown>}
+ */
+export function _makeQuery(descriptor) {
+  const { path } = descriptor || {};
+  return function ruactQueryCall(params) {
+    const url = buildQueryUrl(path, params);
+    return ruactQueryGet(url, path);
+  };
+}
+
+/**
+ * Story 9.5 — React hook for reading a server query. Pass a query reference
+ * (the codegen-emitted `_makeQuery` accessor) and optional params; the hook
+ * issues `GET /q/<jsId>` on mount (and whenever the serialized params change)
+ * and returns `{ data, loading, error }`:
+ *
+ *   - `loading` is true until the first resolution;
+ *   - `data` carries the JSON-decoded response on success (and the last
+ *     successful value while a subsequent refetch is in flight);
+ *   - `error` carries the structured `RuactActionError` (or a transport
+ *     `Error`) on failure, and is reset to `null` on a successful refetch.
+ *
+ * A superseded in-flight response (params changed, or the component
+ * unmounted) is dropped — the hook never sets state for a stale request.
+ *
+ * Request de-duplication across components is Story 9.6; this hook fetches
+ * once per mount.
+ *
+ * @param {(params?: Record<string, unknown>) => Promise<unknown>} reference
+ * @param {Record<string, unknown>} [params]
+ * @returns {{ data: unknown, loading: boolean, error: unknown }}
+ */
+export function useQuery(reference, params) {
+  const [state, setState] = useState({ data: undefined, loading: true, error: null });
+
+  // Re-run the effect by VALUE, not identity: an inline `{ q: input }` literal
+  // is a fresh object every render, which would refetch on every render if used
+  // directly as a dependency. Serializing collapses equal params to one key.
+  const paramsKey = params == null ? "" : JSON.stringify(params);
+
+  useEffect(() => {
+    let active = true;
+    setState((prev) => ({ data: prev.data, loading: true, error: null }));
+    // Wrap in Promise.resolve so a synchronous throw inside `reference`
+    // (e.g. a non-primitive param rejected by `buildQueryUrl`) lands on the
+    // error branch instead of escaping the effect.
+    Promise.resolve()
+      .then(() => reference(params))
+      .then((data) => {
+        if (active) setState({ data, loading: false, error: null });
+      })
+      .catch((error) => {
+        if (active) setState((prev) => ({ data: prev.data, loading: false, error }));
+      });
+    return () => {
+      active = false;
+    };
+    // `params` is intentionally tracked via the serialized `paramsKey`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reference, paramsKey]);
+
+  return state;
+}
+
 // Story 8.2 — picks the argument the wire request should serialize from
 // `_makeRef`'s call-args, following the rules documented in the JSDoc
 // above. Exported through `__internals` for the vitest suite (AC10) — it
@@ -218,6 +310,8 @@ export const __internals = {
   pickWirePayload,
   interpolatePath,
   followRedirectIfPresent,
+  buildQueryUrl,
+  buildQueryFetchInit,
 };
 
 // v1 (Story 8.1) — POST to the synthetic endpoint. A thin wrapper over the
@@ -265,6 +359,88 @@ async function ruactInvoke({ method, url, args, label }) {
   return parseResponse(response);
 }
 
+// Story 9.5 — the GET fetch core for queries. Mirrors `ruactInvoke`'s
+// structure (loud transport error, structured `RuactActionError` on !ok,
+// shared `parseResponse`) but for a read: GET, no body, no CSRF.
+async function ruactQueryGet(url, label) {
+  let response;
+  try {
+    response = await fetch(url, buildQueryFetchInit());
+  } catch (err) {
+    throw new Error(
+      `ruact query ${label} request failed: ${err?.message ?? err}`,
+    );
+  }
+  if (!response.ok) {
+    const body = await safeParseBody(response);
+    throw new RuactActionError({ name: label, status: response.status, body, response });
+  }
+  return parseResponse(response);
+}
+
+// Story 9.5 — serialize the params object into the GET query string. FR88
+// wire format: only primitives (string / number / boolean / null) are
+// encoded. Arrays and objects throw a `TypeError` client-side for immediate
+// local feedback; the server-side sanitization in `query_dispatch.rb` is the
+// authoritative gate. `null` is encoded as an empty value (`key=`).
+function buildQueryUrl(path, params) {
+  if (params == null) return path;
+  if (typeof params !== "object" || Array.isArray(params)) {
+    throw new TypeError(
+      `ruact useQuery for ${path}: params must be a plain object of ` +
+        "string / number / boolean / null values",
+    );
+  }
+  const search = new URLSearchParams();
+  // `null` is sent as a BARE key (`?q`, no `=`) — Rack parses that as `nil`,
+  // whereas `?q=` parses as `""`. This keeps `null` distinguishable from the
+  // empty string at the Ruby query-method boundary (the server allowlist
+  // accepts both `nil` and `String`). Bare keys are collected separately
+  // because `URLSearchParams` always emits `key=`; their order relative to
+  // the `=`-valued params is irrelevant server-side.
+  const bareKeys = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    if (value === null) {
+      bareKeys.push(encodeURIComponent(key));
+    } else if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      search.append(key, String(value));
+    } else {
+      throw new TypeError(
+        `ruact useQuery for ${path}: param "${key}" must be a string, number, ` +
+          "boolean, or null — arrays and objects are rejected",
+      );
+    }
+  }
+  const qs = [search.toString(), ...bareKeys].filter((s) => s.length > 0).join("&");
+  return qs.length === 0 ? path : `${path}?${qs}`;
+}
+
+// Story 9.5 — fetch init for a query GET. No body, no `X-CSRF-Token` (reads
+// are CSRF-free). `defaultHeaders` still apply (e.g. an API-mode
+// `Authorization: Bearer …`), with the gem's own `Accept` winning. Keeps
+// `redirect: "error"` so an auth `redirect_to "/login"` surfaces as a loud
+// failure rather than resolving with the login page HTML.
+function buildQueryFetchInit() {
+  const RESERVED = new Set(["accept"]);
+  const extra =
+    typeof runtimeOptions.defaultHeaders === "function"
+      ? runtimeOptions.defaultHeaders()
+      : runtimeOptions.defaultHeaders;
+  const headers = {};
+  if (extra && typeof extra === "object") {
+    for (const [key, value] of Object.entries(extra)) {
+      if (!RESERVED.has(key.toLowerCase())) headers[key] = value;
+    }
+  }
+  headers.Accept = "application/json";
+  return { method: "GET", credentials: "same-origin", redirect: "error", headers };
+}
+
 // Story 9.3 (D7) — substitute dynamic path segments (`:id`, …) from the single
 // call argument. Values are read BY NAME (FormData.get / object property); the
 // argument is still sent as the body. A missing required segment fails loudly

data/vendor/javascript/ruact-server-functions-runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruact-server-functions-runtime",
-  "version": "0.2.0",
-  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2). Provides `_makeRef(name)` (POSTs to `/__ruact/fn/:name` with CSRF + JSON / FormData support, including the useActionState two-arg shape) and `revalidate(path?)` (Flight refetch via the installed ruact-router).",
+  "version": "0.3.0",
+  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2 + 9.5). Provides `_makeRef(name)` / `_makeServerFunction(descriptor)` (mutations: POST/PUT/PATCH/DELETE with CSRF + JSON / FormData), `revalidate(path?)` (Flight refetch), and `_makeQuery(descriptor)` + `useQuery(ref, params?)` (reads: GET /q/<jsId>, CSRF-free, FR88 primitive params → { data, loading, error }).",
   "type": "module",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -16,7 +16,14 @@
   "scripts": {
     "test": "vitest run"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "vitest": "^2.1.9"
   }
 }

data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+//
+// Story 9.5 — vitest coverage for the read-side runtime: the `useQuery` React
+// hook (loading/data/error transitions, param passing, value-stable refetch)
+// and the `_makeQuery` GET wire format (query-string encoding, FR88 primitive
+// allowlist, CSRF-free init). Runs under jsdom so `@testing-library/react`'s
+// `renderHook` can drive the hook through React's effect lifecycle.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+
+import { useQuery, _makeQuery, RuactActionError, __internals } from "./index.js";
+
+let originalFetch;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+function mockFetchOk(jsonBody, { status = 200, contentType = "application/json" } = {}) {
+  const response = {
+    ok: true,
+    status,
+    headers: { get: (n) => (n.toLowerCase() === "content-type" ? contentType : null) },
+    text: vi.fn().mockResolvedValue(typeof jsonBody === "string" ? jsonBody : JSON.stringify(jsonBody)),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+function mockFetchError(status, bodyText) {
+  const response = {
+    ok: false,
+    status,
+    headers: { get: () => "text/plain" },
+    text: vi.fn().mockResolvedValue(bodyText),
+  };
+  globalThis.fetch = vi.fn().mockResolvedValue(response);
+  return response;
+}
+
+describe("Story 9.5 — useQuery hook contract", () => {
+  it("starts loading, then resolves to { data, loading: false, error: null }", async () => {
+    const ref = vi.fn().mockResolvedValue({ items: [1, 2] });
+    const { result } = renderHook(() => useQuery(ref));
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.data).toBeUndefined();
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.data).toEqual({ items: [1, 2] });
+    expect(result.current.error).toBe(null);
+  });
+
+  it("transitions loading → error on a rejected reference", async () => {
+    const err = new RuactActionError({ name: "/q/categories", status: 500, body: "boom", response: {} });
+    const ref = vi.fn().mockRejectedValue(err);
+    const { result } = renderHook(() => useQuery(ref));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBe(err);
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it("passes params to the query reference", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const params = { q: "ruby", limit: 5 };
+    renderHook(() => useQuery(ref, params));
+
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+    expect(ref).toHaveBeenCalledWith(params);
+  });
+
+  it("does not refetch when params are value-equal across renders", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "a" } }); // fresh object literal, identical value
+    await Promise.resolve();
+    expect(ref).toHaveBeenCalledTimes(1);
+  });
+
+  it("refetches when params change by value", async () => {
+    const ref = vi.fn().mockResolvedValue("ok");
+    const { rerender } = renderHook(({ p }) => useQuery(ref, p), {
+      initialProps: { p: { q: "a" } },
+    });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(1));
+
+    rerender({ p: { q: "b" } });
+    await waitFor(() => expect(ref).toHaveBeenCalledTimes(2));
+    expect(ref).toHaveBeenLastCalledWith({ q: "b" });
+  });
+
+  it("surfaces a synchronous throw from the reference as an error (not an unhandled rejection)", async () => {
+    const ref = () => {
+      throw new TypeError("params must be a plain object");
+    };
+    const { result } = renderHook(() => useQuery(ref, [1, 2]));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.error).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("Story 9.5 — useQuery against _makeQuery end-to-end (GET wire)", () => {
+  it("issues GET /q/<id>?<params> and resolves the JSON body through the hook", async () => {
+    mockFetchOk([{ value: 1, label: "Books" }]);
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    const [url, init] = globalThis.fetch.mock.calls[0];
+    expect(url).toBe("/q/categories?q=bo");
+    expect(init.method).toBe("GET");
+    expect(result.current.data).toEqual([{ value: 1, label: "Books" }]);
+  });
+
+  it("carries the structured RuactActionError into the hook's error on a 4xx", async () => {
+    mockFetchError(400, "bad");
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    const { result } = renderHook(() => useQuery(search));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBeInstanceOf(RuactActionError);
+    expect(result.current.error.status).toBe(400);
+  });
+});
+
+describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
+  const { buildQueryUrl, buildQueryFetchInit } = __internals;
+
+  it("omits the query string entirely when no params are given", () => {
+    expect(buildQueryUrl("/q/categories", undefined)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", null)).toBe("/q/categories");
+    expect(buildQueryUrl("/q/categories", {})).toBe("/q/categories");
+  });
+
+  it("encodes string / number / boolean primitives", () => {
+    expect(buildQueryUrl("/q/search", { q: "a b", limit: 5, active: true })).toBe(
+      "/q/search?q=a+b&limit=5&active=true",
+    );
+  });
+
+  it("encodes null as a BARE key (Rack parses `?q` as nil, distinct from `?q=` empty string)", () => {
+    expect(buildQueryUrl("/q/search", { q: null })).toBe("/q/search?q");
+    // value-bearing params keep `key=value`; a null alongside is a bare key
+    expect(buildQueryUrl("/q/search", { limit: 5, q: null })).toBe("/q/search?limit=5&q");
+  });
+
+  it("rejects an array value (FR88 — arrays are not primitives)", () => {
+    expect(() => buildQueryUrl("/q/search", { q: [1, 2] })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects an object value", () => {
+    expect(() => buildQueryUrl("/q/search", { q: { deep: 1 } })).toThrow(/arrays and objects are rejected/);
+  });
+
+  it("rejects a top-level array of params", () => {
+    expect(() => buildQueryUrl("/q/search", [1, 2])).toThrow(/plain object/);
+  });
+
+  it("builds a GET init with Accept JSON, no body, no CSRF, redirect: error", () => {
+    const init = buildQueryFetchInit();
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+    expect(init.headers.Accept).toBe("application/json");
+    expect(init.headers["X-CSRF-Token"]).toBeUndefined();
+    expect(init.redirect).toBe("error");
+  });
+});

data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs

@@ -49,12 +49,18 @@ const RESERVED_JS_IDENTIFIERS = new Set([
 ]);
 
 // Story 8.2 R12 (2026-05-17) — names ALREADY bound at module top by the
-// codegen itself: `_makeRef` (imported from the runtime) and `revalidate`
-// (re-exported unconditionally from the runtime). A snapshot that
-// declared either as an action `js_identifier` would emit a duplicate
-// binding and crash at module-load time. Mirrors Ruby
-// `NameBridge::RESERVED_BY_RUACT`.
-const RESERVED_BY_RUACT = new Set(["_makeRef", "_makeServerFunction", "revalidate"]);
+// codegen itself: the runtime imports (`_makeRef`, `_makeServerFunction`,
+// `_makeQuery`) and the re-exports (`revalidate`, `useQuery`). A snapshot that
+// declared any as a `js_identifier` would emit a duplicate binding and crash
+// at module-load time. Mirrors Ruby `NameBridge::RESERVED_BY_RUACT`.
+// Story 9.5 added `_makeQuery` + `useQuery`.
+const RESERVED_BY_RUACT = new Set([
+  "_makeQuery",
+  "_makeRef",
+  "_makeServerFunction",
+  "revalidate",
+  "useQuery",
+]);
 
 // Story 9.3 — the route-driven snapshot schema version + its verb allowlist.
 // A version-2 snapshot renders `_makeServerFunction({...})` calls; `render`
@@ -62,6 +68,10 @@ const RESERVED_BY_RUACT = new Set(["_makeRef", "_makeServerFunction", "revalidat
 // Mirrors Ruby `Codegen::VERSION_V2` / `V2_HTTP_METHODS`.
 export const VERSION_V2 = 2;
 const V2_HTTP_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+// Story 9.5 — queries are GET-only (the `POST /__ruact/fn/:id` query mechanism
+// is voided by the 2026-06-02 ADR addendum). Mirrors Ruby
+// `Codegen::V2::QUERY_HTTP_METHODS`.
+const V2_QUERY_HTTP_METHODS = new Set(["GET"]);
 
 /**
  * Absolute path to the placeholder runtime bundled inside the gem. Used as the
@@ -305,16 +315,18 @@ function validateSnapshotV2(snapshot) {
     }
     seen.add(fn.js_identifier);
 
-    if (fn.kind !== "action") {
+    if (fn.kind !== "action" && fn.kind !== "query") {
       throw new Error(
         `ruact server-function codegen: v2 snapshot entry "${fn.js_identifier}" has invalid ` +
-          `kind ${JSON.stringify(fn.kind)} (v2 entries are always "action").`,
+          `kind ${JSON.stringify(fn.kind)} (v2 entries are "action" or "query").`,
       );
     }
-    if (!V2_HTTP_METHODS.has(fn.http_method)) {
+    // Story 9.5 — actions carry a mutation verb; queries are GET-only.
+    const allowedMethods = fn.kind === "query" ? V2_QUERY_HTTP_METHODS : V2_HTTP_METHODS;
+    if (!allowedMethods.has(fn.http_method)) {
       throw new Error(
         `ruact server-function codegen: v2 snapshot entry "${fn.js_identifier}" has invalid ` +
-          `http_method ${JSON.stringify(fn.http_method)} (must be POST/PUT/PATCH/DELETE).`,
+          `http_method ${JSON.stringify(fn.http_method)} (must be one of ${JSON.stringify([...allowedMethods])}).`,
       );
     }
     if (typeof fn.path !== "string" || !fn.path.startsWith("/")) {
@@ -369,11 +381,21 @@ function validateSnapshotV2(snapshot) {
 function renderV2(snapshot) {
   validateSnapshotV2(snapshot);
   const { version, generated_at, functions } = snapshot;
+
+  const hasQuery = functions.some((fn) => fn.kind === "query");
+  const hasAction = functions.some((fn) => fn.kind === "action");
+
+  // Story 9.5 — import only what is used. Keep `_makeServerFunction` in the
+  // empty case so the no-functions module stays byte-identical to Story 9.3.
+  const imports = [];
+  if (hasAction || functions.length === 0) imports.push("_makeServerFunction");
+  if (hasQuery) imports.push("_makeQuery");
+
   let out = "";
   out += "// AUTO-GENERATED by vite-plugin-ruact (Story 9.3). DO NOT EDIT.\n";
   out += `// Source: Rails route table (version ${version})\n`;
   out += `// Generated at: ${generated_at}\n`;
-  out += `import { _makeServerFunction } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
+  out += `import { ${imports.join(", ")} } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
 
   if (functions.length === 0) {
     out += "\n// (no server functions exposed yet — add a non-GET route on a Ruact::Server controller)\n";
@@ -386,12 +408,17 @@ function renderV2(snapshot) {
   }
   out += "\n";
   out += `export { revalidate } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
+  // Story 9.5 — `useQuery` re-export ONLY when queries are present (keeps the
+  // action-only / empty modules byte-identical to Story 9.3).
+  if (hasQuery) out += `export { useQuery } from "${RUNTIME_IMPORT_SPECIFIER}";\n`;
   return out;
 }
 
 function renderExportV2(fn) {
-  // Same intersection signature as v1 actions (Story 8.2) — every v2 entry is
-  // an action. Mirrors `Ruact::ServerFunctions::Codegen::ACTION_SIGNATURE`.
+  if (fn.kind === "query") return renderQueryExportV2(fn);
+
+  // The same intersection signature as v1 actions (Story 8.2). Mirrors
+  // `Ruact::ServerFunctions::Codegen::ACTION_SIGNATURE`.
   const signature =
     "((args?: FormData | Record<string, unknown>) => Promise<unknown>) & ((formData: FormData) => Promise<void>)";
   const method = JSON.stringify(String(fn.http_method));
@@ -404,6 +431,22 @@ function renderExportV2(fn) {
   );
 }
 
+// Story 9.5 — a query export binds a `_makeQuery` accessor carrying its GET
+// descriptor `{ path, kind: "query" }`; `useQuery(<id>, …)` consumes it. The
+// signature accepts params only when the query method declares kwargs (FR88).
+// Mirrors `Ruact::ServerFunctions::Codegen::V2.render_query_export`.
+function renderQueryExportV2(fn) {
+  const signature = fn.accepts_params
+    ? "(params: Record<string, unknown>) => Promise<unknown>"
+    : "() => Promise<unknown>";
+  const pathLit = JSON.stringify(String(fn.path));
+  const descriptor = `{ path: ${pathLit}, kind: "query" }`;
+  return (
+    `export const ${fn.js_identifier}: ${signature} =\n` +
+    `  _makeQuery(${descriptor});\n`
+  );
+}
+
 function renderExport(fn) {
   // Story 8.2 (refined 2026-05-17 per review patch R1) — action signature
   // is an intersection of two call signatures so `<form action={fn}>`

data/vendor/javascript/vite-plugin-ruact/server-functions-codegen.test.mjs

@@ -864,3 +864,98 @@ describe("Story 9.3 — route-driven (v2) render + parity", () => {
     expect(jsOutput).toBe(rubyOutput);
   });
 });
+
+describe("Story 9.5 — v2 query entries render + parity", () => {
+  const queryFixture = {
+    version: 2,
+    generated_at: "2026-06-10T00:00:00Z",
+    functions: [
+      {
+        js_identifier: "createPost",
+        kind: "action",
+        http_method: "POST",
+        path: "/posts",
+        segments: [],
+        controller: "posts",
+        action: "create",
+      },
+      {
+        js_identifier: "categories",
+        kind: "query",
+        http_method: "GET",
+        path: "/q/categories",
+        segments: [],
+        accepts_params: false,
+        controller: "CatalogQuery",
+        action: "categories",
+      },
+      {
+        js_identifier: "searchUsers",
+        kind: "query",
+        http_method: "GET",
+        path: "/q/searchUsers",
+        segments: [],
+        accepts_params: true,
+        controller: "CatalogQuery",
+        action: "search_users",
+      },
+    ],
+  };
+
+  it("emits _makeQuery refs with GET descriptors + the useQuery re-export", () => {
+    const out = render(queryFixture);
+    expect(out).toContain('import { _makeServerFunction, _makeQuery } from "ruact/server-functions-runtime";');
+    expect(out).toContain(
+      'export const categories: () => Promise<unknown> =\n  _makeQuery({ path: "/q/categories", kind: "query" });',
+    );
+    expect(out).toContain(
+      'export const searchUsers: (params: Record<string, unknown>) => Promise<unknown> =\n' +
+        '  _makeQuery({ path: "/q/searchUsers", kind: "query" });',
+    );
+    expect(out).toContain('export { useQuery } from "ruact/server-functions-runtime";');
+  });
+
+  it("accepts GET for a query entry but rejects a non-GET verb", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "categories", kind: "query", http_method: "POST", path: "/q/categories", segments: [] },
+        ],
+      }),
+    ).toThrow(/invalid.*http_method/i);
+  });
+
+  it("rejects an unknown kind (action/query only)", () => {
+    expect(() =>
+      render({
+        version: 2,
+        generated_at: "x",
+        functions: [
+          { js_identifier: "x", kind: "mutation", http_method: "GET", path: "/q/x", segments: [] },
+        ],
+      }),
+    ).toThrow(/"action" or "query"/);
+  });
+
+  it("Ruby's render and JS's render produce byte-identical query output", () => {
+    const jsOutput = render(queryFixture);
+    const gemLibPath = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "..",
+      "..",
+      "lib",
+    );
+    const fixtureJson = JSON.stringify(queryFixture);
+    const script =
+      'require "ruact/server_functions/codegen"; ' +
+      'require "json"; ' +
+      `print Ruact::ServerFunctions::Codegen.render(JSON.parse('${fixtureJson}'))`;
+    const rubyOutput = execFileSync("ruby", ["-I", gemLibPath, "-e", script], {
+      encoding: "utf8",
+    });
+    expect(jsOutput).toBe(rubyOutput);
+  });
+});

data/vendor/javascript/vite-plugin-ruact/vitest.config.mjs

@@ -9,7 +9,13 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
-    include: ["**/*.test.mjs", "../ruact-server-functions-runtime/*.test.mjs"],
+    // The runtime's `index.test.mjs` is node-environment + dependency-free, so
+    // it rides along here for a single parity-plus-runtime run. Its jsdom +
+    // React hook tests (`usequery.test.mjs`, Story 9.5) need
+    // `@testing-library/react` from the runtime package's own node_modules and
+    // run via that package's `npm test` — they are intentionally NOT globbed
+    // in here (a `*.test.mjs` glob would pull them in and fail to resolve).
+    include: ["**/*.test.mjs", "../ruact-server-functions-runtime/index.test.mjs"],
     globals: false,
   },
 });