create-nevela 0.1.4 → 0.2.1

package/template/laravel/src/Support/Field.php

@@ -10,7 +10,7 @@ use InvalidArgumentException;
  */
 final class Field
 {
-    public const KINDS = ['string', 'text', 'int', 'float', 'boolean', 'date', 'datetime', 'enum'];
+    public const KINDS = ['string', 'text', 'int', 'float', 'boolean', 'date', 'datetime', 'enum', 'belongsTo', 'file'];
 
     public const FORMATS = [
         'string' => ['email', 'url', 'tel', 'slug', 'color'],
@@ -18,6 +18,9 @@ final class Field
         'int' => ['percent', 'rating'],
     ];
 
+    /** What a file field may accept, in Flare's categories. The MIME types are in Media\FileTypes. */
+    public const ACCEPTS = ['any', 'image', 'pdf', 'video', 'audio', 'text', 'csv', 'document', 'spreadsheet', 'archive'];
+
     /** Shorthand types accepted by --fields, mapped to kind + format. */
     private const ALIASES = [
         'string' => ['string', null], 'text' => ['text', null],
@@ -34,6 +37,9 @@ final class Field
 
     /**
      * @param  list<string>  $options  enum values
+     * @param  string|null  $target  belongsTo: the resource this points at, e.g. "Category"
+     * @param  list<string>  $accept  file: the categories it takes, e.g. ["image"]
+     * @param  string|null  $profile  file: the image profile uploads are optimised with (config nevela.uploads.profiles)
      */
     public function __construct(
         public readonly string $name,
@@ -43,6 +49,9 @@ final class Field
         public readonly bool $unique = false,
         public readonly array $options = [],
         public readonly ?string $label = null,
+        public readonly ?string $target = null,
+        public readonly array $accept = [],
+        public readonly ?string $profile = null,
     ) {
         if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $name)) {
             throw new InvalidArgumentException("Field \"{$name}\" must be camelCase (e.g. publishedAt).");
@@ -64,32 +73,73 @@ final class Field
                 throw new InvalidArgumentException("Enum value \"{$option}\" on \"{$name}\" may only use letters, digits, _ and -.");
             }
         }
+        if ($kind === 'belongsTo') {
+            if ($target === null || ! preg_match('/^[A-Z][A-Za-z0-9]*$/', $target)) {
+                throw new InvalidArgumentException("\"{$name}\" needs the resource it belongs to, e.g. category:belongsTo(Category).");
+            }
+            if (! str_ends_with($name, 'Id') || $name === 'Id') {
+                throw new InvalidArgumentException("A belongsTo field holds an id, so its name ends in \"Id\": {$name}Id.");
+            }
+        }
+        if ($kind === 'file') {
+            if ($accept === []) {
+                throw new InvalidArgumentException("File field \"{$name}\" needs what it accepts, e.g. {$name}:image or {$name}:file(pdf|image).");
+            }
+            foreach ($accept as $category) {
+                if (! in_array($category, self::ACCEPTS, true)) {
+                    throw new InvalidArgumentException("\"{$category}\" is not something \"{$name}\" can accept. Use: ".implode(', ', self::ACCEPTS).'.');
+                }
+            }
+            if ($unique) {
+                throw new InvalidArgumentException("File field \"{$name}\" can't be unique.");
+            }
+            if ($profile !== null && ! preg_match('/^[a-z][a-z0-9-]*$/', $profile)) {
+                throw new InvalidArgumentException("Image profile \"{$profile}\" on \"{$name}\" may only use lower-case letters, digits and -.");
+            }
+        }
     }
 
     /**
      * Parse one `name:type` token. Suffix `?` = optional (nullable), `!` = unique; both may be combined.
-     * Enums: `status:enum(draft|published)`.
+     *
+     *   status:enum(draft|published)
+     *   category:belongsTo(Category)      stored as categoryId
+     *   image:image                       an optimised image; image:image(product) names a profile
+     *   manual:file(pdf|document)         any other upload
      */
     public static function parse(string $token): self
     {
         $token = trim($token);
-        if (! preg_match('/^([A-Za-z][A-Za-z0-9_]*):([a-z]+)(?:\(([^)]*)\))?([?!]{0,2})$/', $token, $m)) {
+        if (! preg_match('/^([A-Za-z][A-Za-z0-9_]*):([A-Za-z_]+)(?:\(([^)]*)\))?([?!]{0,2})$/', $token, $m)) {
             throw new InvalidArgumentException("Invalid field \"{$token}\". Expected name:type, e.g. price:money or status:enum(draft|live)?");
         }
         [, $name, $type, $args, $suffix] = $m + [3 => '', 4 => ''];
         $name = Naming::camel($name);
+        $required = ! str_contains($suffix, '?');
+        $unique = str_contains($suffix, '!');
+        $list = array_values(array_filter(array_map('trim', explode('|', $args)), fn ($v) => $v !== ''));
 
         if ($type === 'enum') {
-            $options = array_values(array_filter(array_map('trim', explode('|', $args)), fn ($v) => $v !== ''));
+            return new self($name, 'enum', null, $required, $unique, $list);
+        }
+        if (in_array($type, ['belongsTo', 'belongs_to', 'belongsto'], true)) {
+            // "category" and "categoryId" both mean the column category_id.
+            $name = str_ends_with($name, 'Id') ? $name : $name.'Id';
 
-            return new self($name, 'enum', null, ! str_contains($suffix, '?'), str_contains($suffix, '!'), $options);
+            return new self($name, 'belongsTo', null, $required, $unique, target: $list[0] ?? Naming::pascal(substr($name, 0, -2)));
+        }
+        if ($type === 'image') {
+            return new self($name, 'file', null, $required, $unique, accept: ['image'], profile: $list[0] ?? null);
+        }
+        if ($type === 'file') {
+            return new self($name, 'file', null, $required, $unique, accept: $list ?: ['any']);
         }
         if (! isset(self::ALIASES[$type])) {
-            throw new InvalidArgumentException("Unknown type \"{$type}\" on \"{$name}\". Use one of: ".implode(', ', array_keys(self::ALIASES)).', enum(a|b).');
+            throw new InvalidArgumentException("Unknown type \"{$type}\" on \"{$name}\". Use one of: ".implode(', ', array_keys(self::ALIASES)).', enum(a|b), belongsTo(Resource), image, file(pdf|…).');
         }
         [$kind, $format] = self::ALIASES[$type];
 
-        return new self($name, $kind, $format, ! str_contains($suffix, '?'), str_contains($suffix, '!'));
+        return new self($name, $kind, $format, $required, $unique);
     }
 
     /** @param array<string, mixed> $data */
@@ -103,6 +153,9 @@ final class Field
             (bool) ($data['unique'] ?? false),
             array_values($data['options'] ?? []),
             $data['label'] ?? null,
+            $data['target'] ?? null,
+            array_values($data['accept'] ?? []),
+            $data['profile'] ?? null,
         );
     }
 
@@ -113,6 +166,9 @@ final class Field
             'kind' => $this->kind,
             'format' => $this->format,
             'options' => $this->options ?: null,
+            'target' => $this->target,
+            'accept' => $this->accept ?: null,
+            'profile' => $this->profile,
             'required' => $this->required ? null : false,
             'unique' => $this->unique ?: null,
             'label' => $this->label,
@@ -126,17 +182,30 @@ final class Field
 
     public function label(): string
     {
-        return $this->label ?? Naming::humanize($this->name);
+        // "categoryId" reads as "Category", which is what the picker shows.
+        return $this->label ?? Naming::humanize($this->kind === 'belongsTo' ? substr($this->name, 0, -2) : $this->name);
+    }
+
+    /** belongsTo: the name of the relation on the model, e.g. "category" for categoryId. */
+    public function relation(): string
+    {
+        return substr($this->name, 0, -2);
+    }
+
+    /** Whether this is a file field that takes images only, and so is optimised and shown as a picture. */
+    public function isImage(): bool
+    {
+        return $this->kind === 'file' && $this->accept === ['image'];
     }
 
     public function sortable(): bool
     {
-        return $this->kind !== 'text';
+        return ! in_array($this->kind, ['text', 'file'], true);
     }
 
     public function filterable(): bool
     {
-        return $this->kind !== 'text';
+        return ! in_array($this->kind, ['text', 'file'], true);
     }
 
     public function searchable(): bool

package/template/laravel/src/Support/TemplateSource.php

@@ -27,7 +27,7 @@ final class TemplateSource
     private const GITHUB = 'https://codeload.github.com/MarkColeMukisa/nevela/tar.gz/refs/tags/v%s';
 
     /** Never part of an app's dashboard: build output, installs and local settings. */
-    private const NEVER = ['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts'];
+    private const NEVER = ['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts', 'AGENTS.md', 'CLAUDE.md'];
 
     /**
      * @return array{files: array<string, string>, from: string} path => contents, and where it came from

package/template/web/app/api/[...path]/route.ts

@@ -0,0 +1,87 @@
+import type { NextRequest } from "next/server";
+import { API_URL, sessionToken } from "@/lib/laravel";
+
+/**
+ * The browser's way to the Laravel API, for the few things a server action can't do:
+ *
+ * - reading, for the relation picker's search (`/api/categories?q=…`),
+ * - showing stored files (`/api/_nevela/files/<key>`), and
+ * - uploading one (`PUT /api/_nevela/uploads/<Resource>/<field>`), which needs the
+ *   browser's upload progress and is larger than a server action accepts.
+ *
+ * The token stays in its httpOnly cookie: it is read here, on the server, and sent on
+ * as a Bearer token. Laravel still decides what the person may see or store. Everything
+ * else that changes data goes through the server actions, so nothing but an upload is
+ * let through here as a write.
+ */
+export const dynamic = "force-dynamic";
+
+/** Larger than any field allows; Laravel enforces the real limit. This only stops a runaway request early. */
+const MAX_UPLOAD_BYTES = 64 * 1024 * 1024;
+
+/**
+ * What is passed back from Laravel's answer. Not its length or encoding: fetch() hands
+ * over the body already decompressed, so the length Laravel gave may no longer be true.
+ */
+const RESPONSE_HEADERS = ["content-type", "cache-control", "etag", "last-modified", "location", "x-content-type-options"];
+
+type Context = { params: Promise<{ path: string[] }> };
+
+function target(path: string[], search: string): string | null {
+  if (path.some((segment) => segment === "" || segment === "." || segment === "..")) return null;
+  return `${API_URL}/${path.map(encodeURIComponent).join("/")}${search}`;
+}
+
+async function forward(url: string, init: RequestInit, withToken: boolean): Promise<Response> {
+  const headers = new Headers(init.headers);
+  headers.set("Accept", headers.get("Accept") ?? "application/json");
+  const token = withToken ? await sessionToken() : undefined;
+  if (token) headers.set("Authorization", `Bearer ${token}`);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(url, { ...init, headers, cache: "no-store", redirect: "manual" });
+  } catch {
+    return Response.json({ error: "Can't reach the API. Is the Laravel app running?" }, { status: 502 });
+  }
+  const passed = new Headers();
+  for (const name of RESPONSE_HEADERS) {
+    const value = upstream.headers.get(name);
+    if (value) passed.set(name, value);
+  }
+  return new Response(upstream.status === 204 || upstream.status === 304 ? null : upstream.body, { status: upstream.status, headers: passed });
+}
+
+export async function GET(request: NextRequest, context: Context) {
+  const { path } = await context.params;
+  const url = target(path, request.nextUrl.search);
+  if (!url) return Response.json({ error: "Not found." }, { status: 404 });
+
+  // Stored files are public and cacheable, so they are asked for without the token.
+  const isFile = path[0] === "_nevela" && path[1] === "files";
+  const conditional: Record<string, string> = {};
+  for (const name of ["if-none-match", "if-modified-since"]) {
+    const value = request.headers.get(name);
+    if (value) conditional[name] = value;
+  }
+  return forward(url, { method: "GET", headers: { Accept: request.headers.get("accept") ?? "application/json", ...conditional } }, !isFile);
+}
+
+export async function PUT(request: NextRequest, context: Context) {
+  const { path } = await context.params;
+  const url = target(path, request.nextUrl.search);
+  if (!url || path[0] !== "_nevela" || path[1] !== "uploads") {
+    return Response.json({ error: "Only uploads are sent this way. Records are saved through the dashboard." }, { status: 405 });
+  }
+  if (Number(request.headers.get("content-length") ?? 0) > MAX_UPLOAD_BYTES) {
+    return Response.json({ error: "That file is too large to upload." }, { status: 413 });
+  }
+
+  // Read whole, then sent with its length: PHP's development server can't take a body
+  // that arrives in chunks, which is how a stream would be passed on.
+  const body = await request.arrayBuffer();
+  if (body.byteLength > MAX_UPLOAD_BYTES) {
+    return Response.json({ error: "That file is too large to upload." }, { status: 413 });
+  }
+  return forward(url, { method: "PUT", body, headers: { "Content-Type": request.headers.get("content-type") ?? "application/octet-stream" } }, true);
+}

package/template/web/app/dashboard/actions.ts

@@ -4,6 +4,7 @@ import { revalidatePath } from "next/cache";
 import { can, storedFields, type PolicyAction } from "@flaredev/core";
 import type { FieldIssue } from "@/lib/resource/store";
 import { toCsv } from "@/lib/csv";
+import { fileUrl } from "@/lib/files";
 import { resourcePath, dashboardSession, dashboardStore, policyFor } from "@/lib/dashboard";
 
 export type ActionResult<T = unknown> =
@@ -111,17 +112,33 @@ export async function updateRecordAction(resourceName: string, id: string, input
   return result;
 }
 
-const NO_FILES: ActionResult<never> = { ok: false, status: 501, error: "File fields aren't supported by Nevela yet." };
-
-/** File uploads go through Laravel's filesystem once Nevela generates file fields (see the roadmap). */
+/**
+ * Where the browser sends a file for a file or image field.
+ *
+ * The address is this app's own /api route, which passes the file to Laravel with the
+ * person's token. Laravel checks the type, the size and the contents, optimises an image,
+ * and answers with the key it stored the file under: that key, not the empty one here, is
+ * what the form keeps.
+ */
 export async function createUploadUrlAction(
-  _resourceName: string,
-  _fieldKey: string,
-  _file: { name: string; type: string; size: number },
+  resourceName: string,
+  fieldKey: string,
+  file: { name: string; type: string; size: number },
 ): Promise<ActionResult<{ url: string; key: string }>> {
-  return NO_FILES;
+  const { allowed: inAdmin, role } = await dashboardSession();
+  const policy = policyFor(resourceName);
+  if (!inAdmin || !(can(policy, role, "create") || can(policy, role, "update"))) return forbidden("Your role can't add files to this record.");
+
+  const field = dashboardStore(resourceName).resource.fields[fieldKey];
+  if (!field || field.kind !== "file") return { ok: false, status: 404, error: "That isn't a file field." };
+
+  const query = new URLSearchParams({ name: file.name });
+  return { ok: true, data: { url: `/api/_nevela/uploads/${encodeURIComponent(resourceName)}/${encodeURIComponent(fieldKey)}?${query}`, key: "" } };
 }
 
-export async function createReadUrlAction(_resourceName: string, _fieldKey: string, _key: string, _downloadAs?: string): Promise<ActionResult<{ url: string }>> {
-  return NO_FILES;
+/** The address of a stored file. Kept for code that asks for one; the dashboard builds it with fileUrl(). */
+export async function createReadUrlAction(_resourceName: string, _fieldKey: string, key: string): Promise<ActionResult<{ url: string }>> {
+  const { allowed: inAdmin } = await dashboardSession();
+  if (!inAdmin) return forbidden();
+  return { ok: true, data: { url: fileUrl(key) } };
 }

package/template/web/components/dashboard/dashboard-header.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useSyncExternalStore } from "react";
 import Link from "next/link";
 import { BellIcon, MoonIcon, SunIcon } from "lucide-react";
 import { Button } from "@/components/ui/button";
@@ -30,9 +30,31 @@ function applyTheme(theme: Theme) {
   if (theme !== "system") root.classList.add(theme);
 }
 
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+function watchSystemTheme(onChange: () => void) {
+  const query = window.matchMedia(DARK_QUERY);
+  query.addEventListener("change", onChange);
+  return () => query.removeEventListener("change", onChange);
+}
+
+/**
+ * Whether the device prefers dark. The server can't know, so it and the first render in
+ * the browser both say no, and the real answer follows straight after: reading it during
+ * that first render would give the browser a different page from the one the server sent.
+ */
+function useSystemDark() {
+  return useSyncExternalStore(
+    watchSystemTheme,
+    () => window.matchMedia(DARK_QUERY).matches,
+    () => false,
+  );
+}
+
 export function DashboardHeader({ user, initialTheme, notices = [] }: { user: DashboardUser; initialTheme: Theme; notices?: Notice[] }) {
   const [theme, setTheme] = useState<Theme>(initialTheme);
-  const dark = theme === "dark" || (theme === "system" && typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+  const systemDark = useSystemDark();
+  const dark = theme === "dark" || (theme === "system" && systemDark);
   const needsAttention = notices.some((notice) => notice.tone === "warning");
 
   return (

package/template/web/components/dashboard/fields/file-cell.tsx

@@ -1,55 +1,20 @@
-"use client";
-
-import { useEffect, useState } from "react";
 import { FileIcon } from "lucide-react";
-import { createReadUrlAction } from "@/app/dashboard/actions";
-
-/** Keys that are worth showing rather than naming. */
-const isImageKey = (key: string) => /\.(png|jpe?g|gif|webp|avif)$/i.test(key);
-
-/** "products/2026/09/kettle-a1b2c3.png" → "kettle-a1b2c3.png" */
-const basename = (key: string) => key.slice(key.lastIndexOf("/") + 1);
+import { fileName, fileUrl, isImageKey } from "@/lib/files";
 
 /**
  * A stored file in a table cell or a record's detail.
  *
- * Objects in the bucket are private, so there is no URL to put in `src` — one has to
- * be signed, which is a server action, which makes this a client component. The same
- * round trip the form field does, for the same reason.
- *
- * An image becomes a thumbnail; anything else is its filename, which is the useful
- * part of a key nobody wants to read in full.
+ * An image becomes its thumbnail: the small rendition Laravel made when the file was
+ * uploaded, so a table of fifty products downloads fifty small pictures, not fifty
+ * full-size ones. Anything else is its filename, which is the useful part of a key
+ * nobody wants to read in full.
  */
-export function FileCell({
-  resourceName,
-  fieldKey,
-  value,
-  size = 36,
-}: {
-  resourceName: string;
-  fieldKey: string;
-  value: string;
-  size?: number;
-}) {
-  const [url, setUrl] = useState<string | null>(null);
-  const image = isImageKey(value);
-
-  useEffect(() => {
-    if (!image) return;
-    let cancelled = false;
-    void createReadUrlAction(resourceName, fieldKey, value).then((result) => {
-      if (!cancelled && result.ok) setUrl(result.data.url);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [image, value, resourceName, fieldKey]);
-
-  if (!image) {
+export function FileCell({ value, size = 36 }: { resourceName?: string; fieldKey?: string; value: string; size?: number }) {
+  if (!isImageKey(value)) {
     return (
       <span className="inline-flex items-center gap-1.5 text-muted-foreground">
         <FileIcon aria-hidden="true" className="size-3.5" />
-        <span className="max-w-[16ch] truncate">{basename(value)}</span>
+        <span className="max-w-[16ch] truncate">{fileName(value)}</span>
       </span>
     );
   }
@@ -59,10 +24,8 @@ export function FileCell({
       className="inline-flex items-center justify-center overflow-hidden rounded-md border bg-muted align-middle"
       style={{ width: size, height: size }}
     >
-      {url ? (
-        // eslint-disable-next-line @next/next/no-img-element -- signed, short-lived URL
-        <img src={url} alt="" width={size} height={size} className="size-full object-cover" />
-      ) : null}
+      {/* eslint-disable-next-line @next/next/no-img-element -- already the right size; next/image would resize it again */}
+      <img src={fileUrl(value, "thumb")} alt="" width={size} height={size} loading="lazy" decoding="async" className="size-full object-cover" />
     </span>
   );
 }

package/template/web/components/dashboard/fields/file-field.tsx

@@ -11,9 +11,10 @@ import {
   sniffMatches,
   type FileField as FileFieldDef,
 } from "@flaredev/core";
-import { createReadUrlAction, createUploadUrlAction } from "@/app/dashboard/actions";
+import { createUploadUrlAction } from "@/app/dashboard/actions";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
+import { fileName, fileUrl, isImageKey } from "@/lib/files";
 import { cn } from "@/lib/utils";
 
 interface Props {
@@ -29,11 +30,7 @@ interface Props {
 
 type Upload = { name: string; loaded: number; total: number; abort: () => void };
 
-/** "contacts/avatar/2026/09/<uuid>-me.png" → "me.png" */
-const fileName = (key: string) => key.split("/").pop()!.replace(/^[0-9a-f-]{36}-/, "");
-
 const IMAGE_TYPES = new Set<string>(FILE_CATEGORIES.image);
-const isImageKey = (key: string) => /\.(png|jpe?g|gif|webp|avif)$/i.test(key);
 
 const oneDecimal = new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 });
 const whole = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 });
@@ -58,21 +55,26 @@ const capitalize = (text: string) => text.charAt(0).toUpperCase() + text.slice(1
 /** "image/png" → "PNG", used when a file's contents don't match its type. */
 const typeName = (type: string) => (type.split("/")[1] ?? type).replace(/^vnd\..*\./, "").toUpperCase();
 
-/** PUT with progress events, which fetch() can't report for uploads. */
+/**
+ * PUT with progress events, which fetch() can't report for uploads.
+ *
+ * Resolves with the key the file was stored under. Laravel chooses it, because an image
+ * is optimised on the way in and may come out as a different type from the one sent.
+ */
 function put(url: string, file: File, onProgress: (loaded: number) => void, signal: { abort?: () => void }) {
-  return new Promise<void>((resolve, reject) => {
+  return new Promise<string | undefined>((resolve, reject) => {
     const request = new XMLHttpRequest();
     signal.abort = () => request.abort();
     request.upload.onprogress = (event) => onProgress(event.loaded);
     request.onload = () => {
-      if (request.status >= 200 && request.status < 300) return resolve();
-      let message = `Upload failed (${request.status}).`;
+      let answer: { error?: string; key?: string } = {};
       try {
-        message = (JSON.parse(request.responseText) as { error?: string }).error ?? message;
+        answer = JSON.parse(request.responseText) as typeof answer;
       } catch {
-        // Not JSON: keep the status message.
+        // Not JSON: the status says what happened.
       }
-      reject(new Error(message));
+      if (request.status >= 200 && request.status < 300) return resolve(answer.key);
+      reject(new Error(answer.error ?? `Upload failed (${request.status}).`));
     };
     request.onerror = () => reject(new Error("Upload failed. Check your connection and try again."));
     request.onabort = () => reject(new DOMException("Upload cancelled.", "AbortError"));
@@ -83,9 +85,10 @@ function put(url: string, file: File, onProgress: (loaded: number) => void, sign
 }
 
 /**
- * Upload widget for a `file:[…]` field. Checks type, size and contents in the browser
- * first (the server repeats every check), uploads straight to storage through a signed
- * URL with progress, and stores the object key in the form.
+ * Upload widget for a file or image field. Checks type, size and contents in the browser
+ * first (Laravel repeats every check), uploads with progress, and stores the key Laravel
+ * answers with in the form. An image is optimised as it arrives: resized to the field's
+ * profile, with its smaller renditions made alongside.
  */
 export function FileField({ id, value, onChange, invalid, disabled, field, resourceName, fieldKey }: Props) {
   const input = useRef<HTMLInputElement>(null);
@@ -104,15 +107,8 @@ export function FileField({ id, value, onChange, invalid, disabled, field, resou
 
   // Thumbnail for a stored image (a local preview replaces it while uploading).
   useEffect(() => {
-    if (!value || !isImageKey(value)) return setPreview(null);
-    let cancelled = false;
-    void createReadUrlAction(resourceName, fieldKey, value).then((result) => {
-      if (!cancelled && result.ok) setPreview(result.data.url);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [value, resourceName, fieldKey]);
+    setPreview(value && isImageKey(value) ? fileUrl(value, "thumb") : null);
+  }, [value]);
 
   async function check(file: File): Promise<string | null> {
     const type = file.type || "application/octet-stream";
@@ -142,8 +138,8 @@ export function FileField({ id, value, onChange, invalid, disabled, field, resou
     try {
       const signed = await createUploadUrlAction(resourceName, fieldKey, { name: file.name, type: contentType, size: file.size });
       if (!signed.ok) throw new Error(signed.error);
-      await put(signed.data.url, file, (loaded) => setUpload((current) => current && { ...current, loaded }), signal);
-      onChange(signed.data.key);
+      const stored = await put(signed.data.url, file, (loaded) => setUpload((current) => current && { ...current, loaded }), signal);
+      onChange(stored ?? signed.data.key);
       setStatus(`${file.name} uploaded`);
     } catch (cause) {
       const cancelled = cause instanceof DOMException && cause.name === "AbortError";
@@ -157,10 +153,8 @@ export function FileField({ id, value, onChange, invalid, disabled, field, resou
     }
   }
 
-  async function open() {
-    const result = await createReadUrlAction(resourceName, fieldKey, value);
-    if (result.ok) window.open(result.data.url, "_blank", "noopener");
-    else setError(result.error);
+  function open() {
+    window.open(fileUrl(value), "_blank", "noopener");
   }
 
   function remove() {
@@ -191,7 +185,7 @@ export function FileField({ id, value, onChange, invalid, disabled, field, resou
   const thumbnail = (
     <div className="flex size-16 shrink-0 items-center justify-center overflow-hidden rounded-md border bg-muted">
       {preview ? (
-        // eslint-disable-next-line @next/next/no-img-element -- signed, short-lived URL
+        // eslint-disable-next-line @next/next/no-img-element -- a local preview, or a thumbnail already the right size
         <img src={preview} alt="" width={64} height={64} className="size-full object-cover" />
       ) : (
         <FileIcon aria-hidden="true" className="size-6 text-muted-foreground" />

package/template/web/lib/files.ts

@@ -0,0 +1,21 @@
+/**
+ * Stored files, as the browser asks for them.
+ *
+ * A record's file field holds a key such as `products/image/2026/10/<uuid>-kettle.webp`.
+ * An image's smaller renditions sit beside it with their name before the extension
+ * (`…-kettle.thumb.webp`), so the address of a thumbnail is worked out from the key with
+ * no lookup. Which renditions exist is set by the field's profile in the Laravel app's
+ * config/nevela.php; asking for one that was never made gets the image itself.
+ */
+
+/** Keys that are worth showing rather than naming. */
+export const isImageKey = (key: string) => /\.(png|jpe?g|gif|webp|avif)$/i.test(key);
+
+/** The address of a stored file, or of one of its renditions ("thumb", "card", …). */
+export function fileUrl(key: string, rendition?: string): string {
+  const path = rendition && isImageKey(key) ? key.replace(/(\.[A-Za-z0-9]+)$/, `.${rendition}$1`) : key;
+  return `/api/_nevela/files/${path.split("/").map(encodeURIComponent).join("/")}`;
+}
+
+/** "products/image/2026/10/<uuid>-kettle.webp" → "kettle.webp" */
+export const fileName = (key: string) => key.slice(key.lastIndexOf("/") + 1).replace(/^[0-9a-f-]{36}-/, "");

package/template/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -22,7 +22,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.4.0",
     "lucide-react": "^1.46.0",
-    "next": "16.0.4",
+    "next": "16.3.8",
     "radix-ui": "^1.6.7",
     "react": "19.3.0",
     "react-day-picker": "^10.0.1",

package/template.mjs

@@ -24,7 +24,7 @@ export const sources = {
 };
 
 /** Never part of a new app: build output, installs and local settings. */
-const NEVER = new Set(['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts', 'vendor', '.phpunit.result.cache', '.phpunit.cache', 'composer.lock']);
+const NEVER = new Set(['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts', 'AGENTS.md', 'CLAUDE.md', 'vendor', '.phpunit.result.cache', '.phpunit.cache', 'composer.lock']);
 
 function copyTree(from, to, skip = () => false, relative = '') {
   fs.mkdirSync(to, { recursive: true });