ruact 0.0.5 → 0.0.6

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostDeleteDialog.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+// Post delete confirmation — a CONTROLLED, DESIGN-SYSTEM-AGNOSTIC
+// dialog (Story 14.4 / FR103) built on the native HTML <dialog> element — NO
+// shadcn/ui, NO Radix, NO Tailwind. The PARENT owns `open` and provides
+// `onConfirm`; this component owns only its local submit/error state and drives
+// the native modal off the `open` prop (`showModal()`/`close()`). `onConfirm`
+// performs the destroyPost call (DELETE /posts/:id) and reports `{ ok, error? }`:
+//
+//   - on success the parent closes the dialog (in-list removal of the row, or the
+//     server-driven `$redirect` the runtime follows) — no URL is built here;
+//   - on failure the dialog STAYS OPEN and shows the message inline (the gem's
+//     structured-error shape: the exception message in development, the generic
+//     server message in production).
+//
+// There is no Rails `method=delete` fallback — the destroyPost action is the
+// only path. Cancel closes via `onOpenChange(false)`; Escape fires the native
+// `close` event, which we forward to `onOpenChange(false)` to keep the parent
+// state in sync. (The shadcn AlertDialog styling is the opt-in `--shadcn` path —
+// Story 14.5.)
+import { useEffect, useRef, useState } from "react";
+
+type PostRow = { id: number; title: string | null; body: string | null; published: boolean | null; views: number | null; published_on: string | null; published_at: string | null; author_id: number | null };
+
+// FR100 — opt-in call-site contract. INERT for this component: it is rendered
+// only from PostList.tsx (JSX), never from an ERB `<Component>` tag,
+// so the 13.5 preprocess validator never runs against it. Retained for uniformity
+// with the List/Form.
+export const __ruactContract = {
+  props: { post: "required" },
+};
+
+export function PostDeleteDialog({
+  open,
+  onOpenChange,
+  post,
+  onConfirm,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  post: PostRow;
+  onConfirm: () => Promise<{ ok: boolean; error?: string }>;
+}) {
+  const dialogRef = useRef<HTMLDialogElement | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Drive the native <dialog> modal state off the controlled `open` prop.
+  useEffect(() => {
+    const node = dialogRef.current;
+    if (!node) return;
+    if (open && !node.open) node.showModal();
+    if (!open && node.open) node.close();
+  }, [open]);
+
+  async function handleConfirm(event: { preventDefault: () => void }) {
+    // The PARENT closes the dialog (via onOpenChange) only after a successful
+    // delete; a failure leaves it open with the message.
+    event.preventDefault();
+    setError(null);
+    setSubmitting(true);
+    const res = await onConfirm();
+    setSubmitting(false);
+    if (!res.ok) {
+      setError(res.error ?? "Could not delete this post");
+    }
+  }
+
+  return (
+    <dialog ref={dialogRef} onClose={() => onOpenChange(false)}>
+      <h2>Delete “{String(post.title ?? "")}”?</h2>
+      <p>This action cannot be undone.</p>
+      {error && <p>{error}</p>}
+      <p>
+        <button type="button" onClick={() => onOpenChange(false)} disabled={submitting}>
+          Cancel
+        </button>
+        {" "}
+        <button type="button" onClick={handleConfirm} disabled={submitting}>
+          {submitting ? "Deleting…" : "Delete"}
+        </button>
+      </p>
+    </dialog>
+  );
+}

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostForm.tsx

@@ -0,0 +1,216 @@
+"use client";
+
+// Post form — shared by `new` (initial == null) and `edit` (initial
+// == the serialized record). DESIGN-SYSTEM-AGNOSTIC (Story 14.4 / FR103): every
+// field renders a plain, native HTML control mapped to its attribute type
+// (input / textarea / checkbox / select), labelled, with the FR98 server error
+// surfaced inline beneath it — NO shadcn/ui, NO Tailwind, browser-default styling.
+// Submits through the v2 action accessors: createPost (POST /posts) or
+// updatePost (PATCH /posts/:id). On success the controller drives navigation
+// SERVER-SIDE via `redirect_to` (the `$redirect` the runtime follows) — there is
+// no client URL building here. On a validation failure the SAME response carries
+// the FR98 attribute-keyed `errors` map, surfaced inline per field (the client
+// stays on the form). (The richer shadcn controls are the opt-in `--shadcn` path
+// — Story 14.5.)
+//
+// Client-side validation is intentionally NOT here — it is server-only with a
+// full round-trip. The controlled `useState` keeps this dependency-free.
+import { useState, type FormEvent } from "react";
+import { createPost, updatePost } from "@/.ruact/server-functions";
+
+type PostRow = { id: number; title: string | null; body: string | null; published: boolean | null; views: number | null; published_on: string | null; published_at: string | null; author_id: number | null };
+
+// FR100 — opt-in call-site contract: `initial` is OPTIONAL (`new` omits it,
+// `edit` passes the serialized record); each `references` field adds an
+// optional `<name>Options` prop the new/edit views pass. A typo'd prop name
+// fails at preprocess time instead of silently arriving as `undefined`.
+export const __ruactContract = {
+  props: { initial: "optional", authorOptions: "optional" },
+};
+
+export function PostForm({ initial = null, authorOptions = [] }: { initial?: PostRow | null; authorOptions?: { id: number; label: string }[] }) {
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [title, setTitle] = useState(String(initial?.title ?? ""));
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [body, setBody] = useState(String(initial?.body ?? ""));
+  const [published, setPublished] = useState(Boolean(initial?.published ?? false));
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [views, setViews] = useState(String(initial?.views ?? ""));
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [publishedOn, setPublishedOn] = useState(String(initial?.published_on ?? ""));
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [publishedAt, setPublishedAt] = useState(String(initial?.published_at ?? ""));
+  // String-valued state: native controls bind `string` (numbers + refs arrive on
+  // the row as numbers, so coerce here). The controller re-coerces.
+  const [authorId, setAuthorId] = useState(String(initial?.author_id ?? ""));
+  // FR98 — keyed { [attr]: string[] }; `{}` means "no errors" (always present).
+  const [errors, setErrors] = useState<Record<string, string[]>>({});
+  const [saving, setSaving] = useState(false);
+
+  async function handleSubmit(event: FormEvent) {
+    event.preventDefault();
+    setSaving(true);
+    setErrors({});
+
+    const payload = {
+      title: title,
+      body: body,
+      published: published,
+      views: views,
+      published_on: publishedOn,
+      published_at: publishedAt,
+      author_id: authorId,
+    };
+
+    // On success the server returns a `$redirect` and the runtime navigates
+    // away (the code below does not run); on a validation failure we get the
+    // keyed `errors` map back instead.
+    const result = (initial != null
+      ? await updatePost({ id: initial.id, ...payload })
+      : await createPost(payload)) as { errors?: Record<string, string[]> } | null;
+
+    setSaving(false);
+    if (result && result.errors) {
+      setErrors(result.errors);
+    }
+  }
+
+  const errorsFor = (attr: string) => errors[attr] ?? [];
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h1>{initial != null ? `Edit Post #${initial.id}` : "New Post"}</h1>
+
+      {errorsFor("base").length > 0 && (
+        <ul>
+          {errorsFor("base").map((message, i) => (
+            <li key={i}>{message}</li>
+          ))}
+        </ul>
+      )}
+
+      <p>
+        <label htmlFor="title">Title</label>
+        <input
+          id="title"
+          type="text"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("title").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="body">Body</label>
+        <textarea
+          id="body"
+          value={body}
+          onChange={(e) => setBody(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("body").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="published">
+          <input
+            id="published"
+            type="checkbox"
+            checked={published}
+            onChange={(e) => setPublished(e.target.checked)}
+            disabled={saving}
+          />
+          {" "}Published
+        </label>
+        {errorsFor("published").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="views">Views</label>
+        <input
+          id="views"
+          type="number"
+          value={views}
+          onChange={(e) => setViews(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("views").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="published_on">Published on</label>
+        <input
+          id="published_on"
+          type="date"
+          value={publishedOn}
+          onChange={(e) => setPublishedOn(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("published_on").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="published_at">Published at</label>
+        <input
+          id="published_at"
+          type="datetime-local"
+          value={publishedAt}
+          onChange={(e) => setPublishedAt(e.target.value)}
+          disabled={saving}
+        />
+        {errorsFor("published_at").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <label htmlFor="author_id">Author</label>
+        {/* Eager native <select> of controller-provided options (ivar → `authorOptions`
+            prop). For a parent set larger than the generator's REFERENCE_OPTIONS_LIMIT,
+            swap this for a server-search combobox backed by a parent-options read
+            query (opt-in follow-up — that query is out of this scaffold's scope
+            since the parent model isn't scaffolded here). */}
+        <select
+          id="author_id"
+          value={authorId}
+          onChange={(e) => setAuthorId(e.target.value)}
+          disabled={saving}
+        >
+          <option value="">Select author</option>
+          {authorOptions.map((option) => (
+            <option key={option.id} value={String(option.id)}>
+              {option.label}
+            </option>
+          ))}
+        </select>
+        {errorsFor("author_id").map((message, i) => (
+          <span key={i}>{message}</span>
+        ))}
+      </p>
+
+      <p>
+        <button type="submit" disabled={saving}>
+          {saving ? "Saving…" : initial != null ? "Update post" : "Create post"}
+        </button>
+        {" "}
+        <a href={initial != null ? `/posts/${initial.id}` : "/posts"}>Cancel</a>
+      </p>
+    </form>
+  );
+}

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/PostList.tsx

@@ -0,0 +1,269 @@
+"use client";
+
+// Post list — a DESIGN-SYSTEM-AGNOSTIC table (Story 14.4 / FR103). The
+// default scaffold ships plain, native HTML elements styled by the browser /
+// Rails-default CSS — NO shadcn/ui, NO Tailwind, NO table-engine dependency. The
+// collection arrives as a SERVER-RENDERED prop (`posts`); there is no client query
+// for the initial render. A query only enters when the *client* drives the read:
+// the search box calls useQuery(searchPosts, { q }) and swaps in filtered rows as
+// you type. Per-row delete drives a controlled PostDeleteDialog (DELETE
+// /posts/:id via the destroyPost action); on `{ ok: true }` the row is
+// removed from the displayed rows IN PLACE (no reload, no URL built). Column
+// sorting is CLIENT-ONLY — the dataset is the index payload; server-side
+// sort/pagination is Phase-3 territory. (The richer shadcn DataTable styling is
+// the opt-in `--shadcn` path — Story 14.5.)
+import { useState } from "react";
+import { search as searchPosts, destroyPost, useQuery } from "@/.ruact/server-functions";
+import { PostDeleteDialog } from "./PostDeleteDialog";
+
+type PostRow = { id: number; title: string | null; body: string | null; published: boolean | null; views: number | null; published_on: string | null; published_at: string | null; author_id: number | null };
+
+// FR100 — opt-in call-site contract: `posts` is required. The index view passes
+// `<PostList posts={rows} />` (satisfied); a call site that omits it
+// fails at preprocess time, not as a silent `undefined` in the browser.
+export const __ruactContract = {
+  props: { posts: "required" },
+};
+
+// Columns whose values are date/datetime strings: the sort compares these by
+// epoch time (`new Date(value).getTime()`) rather than lexically, so they order
+// chronologically. Generated from the model's date/datetime attributes.
+const DATE_KEYS = new Set<string>(["published_on", "published_at"]);
+
+// Generated client-side comparator (no table engine). Sorts a COPY of the rows
+// by the active key + direction: `null`/`undefined` always sort LAST (so a blank
+// cell never jumps to the top, regardless of direction); date columns compare by
+// time, numbers numerically, booleans false-before-true, everything else via a
+// locale-aware string compare. The direction flip is applied AFTER the null
+// handling, never to it.
+function compareRows(
+  a: PostRow,
+  b: PostRow,
+  sort: { key: string; dir: "asc" | "desc" },
+): number {
+  const av = a[sort.key as keyof PostRow];
+  const bv = b[sort.key as keyof PostRow];
+  if (av == null && bv == null) return 0;
+  if (av == null) return 1;
+  if (bv == null) return -1;
+
+  let result: number;
+  if (DATE_KEYS.has(sort.key)) {
+    result = new Date(String(av)).getTime() - new Date(String(bv)).getTime();
+  } else if (typeof av === "number" && typeof bv === "number") {
+    result = av - bv;
+  } else if (typeof av === "boolean" && typeof bv === "boolean") {
+    result = Number(av) - Number(bv);
+  } else {
+    result = String(av).localeCompare(String(bv));
+  }
+  return sort.dir === "desc" ? -result : result;
+}
+
+// Pull a human-readable message out of the failed-delete result. A thrown
+// RuactActionError (non-2xx) carries the parsed structured-error body, whose
+// `message` the gem shapes per env (the exception message in development, the
+// generic server message in production); a resolved soft-failure may carry a
+// top-level `error`/`message`. Returns undefined when none is present, so the
+// dialog can fall back to its own generic copy.
+function deleteErrorMessage(error: unknown): string | undefined {
+  if (error != null && typeof error === "object") {
+    const carrier = error as { body?: unknown; error?: unknown; message?: unknown };
+    if (carrier.body != null && typeof carrier.body === "object") {
+      const message = (carrier.body as { message?: unknown }).message;
+      if (typeof message === "string" && message.length > 0) return message;
+    }
+    if (typeof carrier.error === "string" && carrier.error.length > 0) return carrier.error;
+    if (typeof carrier.message === "string" && carrier.message.length > 0) return carrier.message;
+  }
+  return undefined;
+}
+
+// A resolved delete is a SUCCESS only on the server-owned success shapes: the
+// in-list default `{ ok: true }`, or the delete-from-show `$redirect` the
+// accessor already followed (which resolves to `null`). Any other resolved shape
+// (e.g. an explicit `{ ok: false }`) is a non-success the dialog surfaces.
+function deleteSucceeded(result: unknown): boolean {
+  if (result === null) return true;
+  return (
+    typeof result === "object" &&
+    (result as { ok?: unknown }).ok === true
+  );
+}
+
+// Per-row actions (AC2) — an Edit link + a Delete TRIGGER that opens the
+// controlled dialog. Each row owns its OWN dialog `open` state (one independent
+// useState), so the dialog opens for exactly one row. `onConfirm` calls
+// destroyPost and, on a server-owned success, asks the List to drop the row
+// in place via `onDeleted`. The agnostic default keeps a single inline actions
+// cell (the responsive overflow menu is a shadcn refinement deferred to the
+// `--shadcn` path — Story 14.5).
+function RowActions({ record, onDeleted }: {
+  record: PostRow;
+  onDeleted: (id: number) => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  async function onConfirm(): Promise<{ ok: boolean; error?: string }> {
+    try {
+      const result = await destroyPost({ id: record.id });
+      if (deleteSucceeded(result)) {
+        onDeleted(record.id);
+        setOpen(false);
+        return { ok: true };
+      }
+      // Resolved but not a success shape → keep the dialog open with the message.
+      return { ok: false, error: deleteErrorMessage(result) };
+    } catch (error) {
+      // Failure (non-2xx structured error) → keep the dialog open, message inline.
+      return { ok: false, error: deleteErrorMessage(error) };
+    }
+  }
+
+  return (
+    <span>
+      <a href={`/posts/${record.id}/edit`}>Edit</a>
+      {" "}
+      <button type="button" onClick={() => setOpen(true)}>
+        Delete
+      </button>
+
+      <PostDeleteDialog
+        open={open}
+        onOpenChange={setOpen}
+        post={record}
+        onConfirm={onConfirm}
+      />
+    </span>
+  );
+}
+
+export function PostList({
+  posts = [],
+  emptyLabel = "No posts yet — create one.",
+}: { posts?: PostRow[]; emptyLabel?: string }) {
+  const [q, setQ] = useState("");
+  const searching = q.trim().length > 0;
+
+  // Ids deleted IN PLACE — a single tombstone list (not a second row cache)
+  // applied to whichever source is displayed, so a delete removes the row
+  // immediately whether it happened on the server-rendered list OR on the live
+  // search results.
+  const [removedIds, setRemovedIds] = useState<number[]>([]);
+
+  // Sort state (AC2) — the active column key + direction, or null when unsorted
+  // (server/insertion order). A new key sorts ascending; clicking the same key
+  // again flips asc↔desc.
+  const [sort, setSort] = useState<{ key: string; dir: "asc" | "desc" } | null>(null);
+
+  // Client-driven read (AC5) — only meaningful while searching. When q is blank
+  // the box is idle and we fall back to the server-rendered rows.
+  const { data: searchData, loading: searchLoading } = useQuery<PostRow[]>(searchPosts, { q: q.trim() });
+
+  const source = searching ? searchData ?? [] : posts;
+  const rows = removedIds.length === 0 ? source : source.filter((row) => !removedIds.includes(row.id));
+  // Always sort a COPY — never mutate the prop/source array.
+  const sortedRows = sort ? [...rows].sort((a, b) => compareRows(a, b, sort)) : rows;
+
+  const onDeleted = (id: number) =>
+    setRemovedIds((current) => (current.includes(id) ? current : [...current, id]));
+
+  // Set the sort to a new key (ascending), or flip the direction when the active
+  // key is clicked again.
+  function toggleSort(key: string) {
+    setSort((current) =>
+      current && current.key === key
+        ? { key, dir: current.dir === "asc" ? "desc" : "asc" }
+        : { key, dir: "asc" },
+    );
+  }
+
+  return (
+    <section>
+      <h1>Posts</h1>
+      <p>
+        <a href="/posts/new">+ New post</a>
+      </p>
+
+      <input
+        type="search"
+        value={q}
+        onChange={(e) => setQ(e.target.value)}
+        placeholder="Search posts…"
+      />
+
+      {searching && searchLoading && <p>Searching…</p>}
+      {!searching && rows.length === 0 && <p>{emptyLabel}</p>}
+      {searching && !searchLoading && rows.length === 0 && (
+        <p>No posts match “{q.trim()}”.</p>
+      )}
+
+      {sortedRows.length > 0 && (
+        <table>
+          <thead>
+            <tr>
+              <th>
+                <button type="button" onClick={() => toggleSort("id")}>ID</button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("title")}>
+                  Title
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("body")}>
+                  Body
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("published")}>
+                  Published
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("views")}>
+                  Views
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("published_on")}>
+                  Published on
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("published_at")}>
+                  Published at
+                </button>
+              </th>
+              <th>
+                <button type="button" onClick={() => toggleSort("author_id")}>
+                  Author
+                </button>
+              </th>
+              <th>Actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {sortedRows.map((row) => (
+              <tr key={row.id}>
+                <td>
+                  <a href={`/posts/${row.id}`}>{row.id}</a>
+                </td>
+                <td>{String(row.title ?? "")}</td>
+                <td>{String(row.body ?? "")}</td>
+                <td>{row.published ? "Yes" : "No"}</td>
+                <td>{String(row.views ?? "")}</td>
+                <td>{row.published_on ? new Date(String(row.published_on)).toLocaleString() : ""}</td>
+                <td>{row.published_at ? new Date(String(row.published_at)).toLocaleString() : ""}</td>
+                <td>{String(row.author_id ?? "")}</td>
+                <td>
+                  <RowActions record={row} onDeleted={onDeleted} />
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </section>
+  );
+}

data/vendor/javascript/vite-plugin-ruact/type-tests/scaffold/agnostic/ambient.d.ts

@@ -0,0 +1,78 @@
+// Story 14.4 (AC5) — AMBIENT stubs so the GENERATED design-system-AGNOSTIC
+// `<Model>List.tsx` / `<Model>Form.tsx` / `<Model>DeleteDialog.tsx` type-check in
+// ISOLATION. The fixtures in this directory are byte-identical to the generator's
+// live agnostic output (a gem rspec example asserts that equality), so
+// type-checking them under `tsconfig.scaffold-agnostic.json` proves the emitted
+// typed components hold the FR99 server boundary with NO design-system dependency.
+//
+// The POINT of this stub is the opposite of the shadcn one (`../ambient.d.ts`):
+// it declares ONLY React + `@/.ruact/server-functions` and deliberately NO
+// `@/components/ui/*` module. So a stray shadcn import in an agnostic template
+// would fail to resolve here and turn the `npm run typecheck` job RED — that
+// unresolved-module failure is the AC5 proof that the agnostic default needs
+// zero `@/components/ui` resolution.
+
+// JSX without `lib: ["dom"]` / `@types/react`: a permissive intrinsic-element
+// table (every native prop is `any`, so `onChange={(e) => …}` etc. need no DOM
+// event types). `jsx: "preserve"` in the tsconfig still type-checks every JSX
+// expression against this namespace.
+declare namespace JSX {
+  interface Element {} // eslint-disable-line @typescript-eslint/no-empty-interface
+  interface ElementClass {} // eslint-disable-line @typescript-eslint/no-empty-interface
+  interface IntrinsicElements {
+    [elem: string]: any;
+  }
+}
+
+// The generated DeleteDialog types its <dialog> ref as `HTMLDialogElement` — the
+// SAME type a real app's `lib: ["dom"]` gives `<dialog ref={…}>` (so the emitted
+// .tsx type-checks end-to-end in the user's typed app, FR99). This isolated
+// harness has no `lib: dom`, so we declare the minimal structural members the
+// generated code touches (`open` / `showModal` / `close`). In a real app this
+// merges with lib.dom's full HTMLDialogElement.
+interface HTMLDialogElement {
+  open: boolean;
+  showModal(): void;
+  close(): void;
+}
+
+declare module "react" {
+  export function useState<S>(initial: S | (() => S)): [S, (next: S | ((prev: S) => S)) => void];
+  // The generated DeleteDialog drives the native <dialog> off a ref + an effect.
+  export function useRef<T>(initial: T): { current: T };
+  export function useEffect(effect: () => void | (() => void), deps?: ReadonlyArray<unknown>): void;
+  // The generated Form's `handleSubmit(event: FormEvent)` only calls
+  // `event.preventDefault()`; a minimal shim keeps the type load-bearing without
+  // pulling in `@types/react`.
+  export interface FormEvent {
+    preventDefault(): void;
+  }
+}
+
+declare module "@/.ruact/server-functions" {
+  // FR88/FR99 wire union — the only param value type a query accessor accepts.
+  type Wire = string | number | boolean | null;
+
+  // The codegen exports a generic `search` from `<Plural>Query#search(q:)`,
+  // typed from the declared `(q:)` kwarg (Story 13.4). The List aliases it
+  // `search<Plural>`.
+  export const search: (params: { q: Wire }) => Promise<unknown>;
+
+  // Action accessors the generated Form imports. Actions are NOT typed by FR99
+  // (only queries are — Story 13.4 decision A), so the accessors take a loose
+  // payload and return `Promise<unknown>`; the Form narrows the result with an
+  // `as { errors?: ... } | null` assertion at the call site.
+  export const createPost: (payload: Record<string, unknown>) => Promise<unknown>;
+  export const updatePost: (payload: Record<string, unknown>) => Promise<unknown>;
+  // The destroy accessor the List's RowActions calls in `onConfirm` (DELETE
+  // /posts/:id). Like the other actions it is not FR99-typed; it returns
+  // `Promise<unknown>` and throws a `RuactActionError` on a non-2xx response.
+  export const destroyPost: (payload: Record<string, unknown>) => Promise<unknown>;
+
+  // Mirrors the runtime declaration (`ruact-server-functions-runtime/index.d.ts`)
+  // — `reference` is the widened accessor shape (Story 13.4), `T` the return type.
+  export function useQuery<T = unknown>(
+    reference: (...args: never[]) => Promise<unknown>,
+    params?: Record<string, unknown>,
+  ): { data: T | undefined; loading: boolean; error: unknown };
+}