cabloy 5.1.101 → 5.1.103

package/.cabloy-version

@@ -1 +1 @@
-5.1.101
+5.1.103

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 5.1.103
+
+### Features
+
+- Add a direct image upload flow for the frontend.
+- Add user-bound media delivery to restrict training media access to authorized users.
+- Unify file and image visibility semantics across delivery flows.
+- Move image signed URL policy configuration to scenes.
+- Add shared serializer transforms for file responses.
+- Align private delivery semantics for native images.
+
+### Bug Fixes
+
+- Defer image rendering to the client.
+- Refresh stale media authorization tokens.
+- Resolve media URL type errors.
+- Bind training media delivery to the requesting user.
+- Restore file upload type validation.
+
+### Improvements
+
+- Use exact media delivery paths.
+- Add fresh query helpers for retrieving current data.
+- Simplify media delivery options and resolver view naming.
+- Align the file upload lifecycle and simplify image upload handling.
+- Reduce exposed public fields and contract surface for files and images.
+- Clarify image transform key naming.
+- Remove native image direct-upload support.
+
+## 5.1.102
+
+### Features
+
+- Keep the upgrade dry-run plan for the current version.
+- Extend Cabloy Basic upgrade overwrite suites.
+
 ## 5.1.101
 
 ### Features

package/CLAUDE.local.md

@@ -0,0 +1,4 @@
+# Local Claude Code Instructions
+
+After implementation, do not launch broad review automatically.
+If a review is needed, keep it scoped to the current diff and report only high-confidence issues.

package/cabloy-docs/.vitepress/config.mjs

@@ -99,6 +99,7 @@ const fullstackGroups = [
         link: '/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map',
       },
       { text: 'Fullstack Image Workflow', link: '/fullstack/image-workflow' },
+      { text: 'Fullstack File Workflow', link: '/fullstack/file-workflow' },
       { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
       {
         text: 'Frontend Metadata Back to Backend',
@@ -233,6 +234,7 @@ export default defineConfig({
             { text: 'Logger Guide', link: '/backend/logger-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Image Guide', link: '/backend/image-guide' },
+            { text: 'File Guide', link: '/backend/file-guide' },
             { text: 'Mail Guide', link: '/backend/mail-guide' },
             { text: 'Serialization Guide', link: '/backend/serialization-guide' },
           ],
@@ -422,6 +424,7 @@ export default defineConfig({
             { text: 'Component Guide', link: '/frontend/component-guide' },
             { text: 'Form Guide', link: '/frontend/form-guide' },
             { text: 'Image Guide', link: '/frontend/image-guide' },
+            { text: 'File Guide', link: '/frontend/file-guide' },
             {
               text: 'Zova Form Under the Hood',
               link: '/frontend/zova-form-under-the-hood',

package/cabloy-docs/backend/file-guide.md

@@ -0,0 +1,148 @@
+# File Guide
+
+This guide describes the Vona file contract in Cabloy Basic: scenes, providers, ingestion, lifecycle, delivery, and DTO-side views.
+
+> Read this with [Frontend File Guide](/frontend/file-guide) and [Fullstack File Workflow](/fullstack/file-workflow). `a-file` is the core module; the built-in provider modules are Native (`file-native`) and Cloudflare R2 (`file-cloudflare`).
+
+## Core model and trust boundary
+
+A file use case is a named backend capability:
+
+- `@FileScene(...)` defines the business policy;
+- `app.bean.file` orchestrates provider storage and lifecycle;
+- a provider owns storage-specific behavior and delivery;
+- business entities persist file IDs, while serializer transforms resolve consumer-facing `DtoFileView` data.
+
+The HTTP client supplies a `fileScene`; it never chooses the provider, client, visibility, bucket, object key, ETag, or storage path. Those values remain backend-owned.
+
+The current defaults are:
+
+| Setting                      | Default              |
+| ---------------------------- | -------------------- |
+| Provider                     | `file-native:native` |
+| Provider client              | `default`            |
+| Visibility                   | private              |
+| Maximum upload size          | 20 MiB               |
+| Direct-upload draft lifetime | 30 minutes           |
+
+Scene `upload` options override global `file.upload` options. Visibility resolves in this order: `FileScene.public`, then the selected provider client's `public`, then global `file.public`, then `false`.
+
+## Define a file scene
+
+Define a scene for every business capability. It owns provider selection, public/private policy, admission constraints, and optional metadata.
+
+```ts
+import { BeanBase } from 'vona';
+import { FileScene } from 'vona-module-a-file';
+
+@FileScene({
+  public: false,
+  upload: {
+    maxSize: 20 * 1024 * 1024,
+    mimeTypes: ['application/pdf', 'application/zip', 'text/plain'],
+    extensions: ['.pdf', '.zip', '.txt'],
+    multiple: true,
+  },
+})
+export class FileSceneDossierFile extends BeanBase {}
+```
+
+The training-record suite implements this pattern in `FileSceneDossierFile`. Extensions are lowercase and include the leading dot. `provider` can be a fixed `{ providerName, clientName }` pair or an async resolver receiving the current Vona context; `meta` can likewise be static or context-derived. Use those resolvers for trusted tenant or user routing, not browser-provided storage choices.
+
+## Provider capabilities
+
+A provider implements `IFileProviderExecute`. Its capabilities determine what a selected scene can do.
+
+| Capability                                    | Requirement   | Meaning                                                                                    |
+| --------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| `upload`, `get`, `delete`, `getDownloadUrl`   | Required      | Normal storage, retrieval, deletion, and delivery                                          |
+| `uploadUrl`                                   | Optional      | Server-side remote URL import                                                              |
+| `createDirectUpload` + `finalizeDirectUpload` | Optional pair | Third-party direct upload; both are required before policy advertises `directUpload: true` |
+| `download`                                    | Optional      | Provider can stream/return a download result instead of only a URL                         |
+
+The public upload-policy response exposes semantic constraints and `directUpload` only. It never exposes a provider name, client name, bucket, object key, ETag, or provider credentials.
+
+Native supports ordinary multipart upload and proxy-style private delivery. It intentionally does **not** implement remote URL import or direct-upload creation/finalization. Cloudflare R2 is registered as `file-cloudflare:cloudflare`; it supports ordinary upload, secure URL import, and direct upload.
+
+## Three ingestion models
+
+### Authenticated multipart upload
+
+`POST /file/upload` is the portable default:
+
+```text
+fileScene + file → backend validation/storage → ready response
+```
+
+It accepts one multipart `fileScene` field and one file. Vona reads the received temporary file, resolves the scene, validates actual size, received multipart MIME type, and filename extension, then stores it with the selected provider. The returned action response is already `ready`.
+
+MIME and extension checks are policy checks, not binary magic-byte inspection. Treat them as one layer of admission control rather than a content-safety scanner.
+
+### Remote HTTPS URL import
+
+`POST /file/upload-url` is an authorized, provider-capability operation. Native rejects it. Cloudflare R2 imports through the shared remote-fetch boundary:
+
+- only HTTPS on port 443, with no URL credentials;
+- at most three redirects, with URL and DNS/IP checks repeated for every hop;
+- each hostname is resolved before connection, all answers must be public, and the validated address is pinned for that request;
+- loopback, private, link-local, multicast, unspecified, reserved, shared, and documentation IPv4/IPv6 ranges are rejected;
+- connection, response, read, and overall deadlines are enforced;
+- bytes stream to a private `0600` temporary file and are limited by the scene's actual-byte policy;
+- the filename is sanitized, while response content type and extension are checked against policy;
+- temporary files are removed on success and failure.
+
+Request-declared size, MIME type, content type, and object key are not persisted remote-file truth. The response headers, transferred bytes, and resolved filename drive validation and storage. A browser field must not fetch an arbitrary URL and forward it to Cabloy; build an explicitly authorized backend consumer when URL import is needed.
+
+### Third-party direct upload
+
+A direct-capable R2 scene uses an explicit lifecycle:
+
+```text
+create draft → browser raw provider transfer → finalize → ready
+```
+
+1. `POST /file/direct-upload` creates a draft and returns a presigned raw-body target.
+2. The browser sends the raw file with the returned method and headers, without adding Cabloy credentials.
+3. `POST /file/direct-upload/finalize` queries the persisted R2 object with `HeadObject`.
+4. Vona verifies object existence, the reserved size, and content type; persists final metadata; and promotes the row to `ready`.
+
+A draft cannot resolve to a file view, receive a download URL, be downloaded, or become a business relation. The scheduled prune job runs every 30 minutes, handles at most 100 expired drafts per execution, deletes provider content, and then marks the row `expired`. Finalization and expiration share a per-file Redlock. If provider deletion fails, the draft remains eligible for a later pruning retry.
+
+Direct finalization validates provider metadata; it does not inspect file magic bytes or re-run filename-extension admission after provider transfer.
+
+## Persist IDs; resolve safe views
+
+Business data persists `TableIdentity` values. Consumer DTOs expose a safe projection using `a-file:resolveView` or `a-file:resolveViews`:
+
+```ts
+@Api.field(
+  v.optional(),
+  v.serializerTransform('a-file:resolveViews', {
+    fieldName: 'dossierFileIds',
+    fileScene: 'training-record:dossierFile',
+  }),
+  v.array(DtoFileView),
+)
+dossierFiles?: DtoFileView[];
+```
+
+A resolved `DtoFileView` contains only completed-file presentation and delivery data: ID, filename, content type, size, visibility, upload time, `downloadUrl`, and signed state. Provider/client identities, bucket, object key, ETag, storage path, raw SDK output, metadata, status, and draft timestamps remain internal.
+
+The serializer also checks the optional `fileScene`. A relation with the wrong scene is rejected rather than silently resolving a file from a different business capability.
+
+## Delivery and trusted backend APIs
+
+Files are private by default. Private delivery can be either a temporary Cabloy proxy URL or a provider-signed R2 URL. `GET /file/download?fileId=...` is route-public so a signed link can be opened. Proxy delivery still requires a temporary token bound to the delivery endpoint and a signed payload whose file ID must match the request query.
+
+When Cabloy streams bytes it can set an attachment filename. When Cabloy redirects to a provider URL, download-versus-inline behavior is controlled by that provider response and the browser.
+
+`app.bean.file` is a trusted backend API and can accept provider/client options, visibility, metadata, and object-key inputs. Do not treat that lower-level API as the browser contract or forward untrusted request values into those fields.
+
+## Backend checklist
+
+1. Define one `@FileScene(...)` per business capability.
+2. Keep provider, visibility, and storage decisions on the server.
+3. Use ordinary multipart upload unless the resolved policy advertises direct upload.
+4. Use URL import only through a provider that implements the secure backend fetch boundary.
+5. Persist IDs and resolve `DtoFileView` relations for consumers.
+6. Write business relations only from ready/finalized responses and preserve signed delivery semantics when changing providers.

package/cabloy-docs/backend/image-guide.md

@@ -170,7 +170,7 @@ If neither is provided, Vona falls back to the configured default variant, which
 
 Vona supports signed delivery in two forms:
 
-- **proxy-signed delivery**: Vona creates a temporary delivery token and redirects through `/image/delivery/:imageId`
+- **proxy-signed delivery**: Vona creates a temporary delivery token and redirects through `/image/delivery?imageId=...`
 - **provider-signed delivery**: the provider generates the final signed URL directly
 
 The built-in defaults differ:
@@ -196,7 +196,7 @@ Representative methods are:
 
 A useful practical boundary is:
 
-- use `BeanImageUploadPolicy` when you need scene resolution and upload-token policy
+- use `BeanImageUploadPolicy` when you need scene resolution and upload policy
 - use `app.bean.image` when you need the actual image lifecycle and delivery behavior
 
 ## Persistence model
@@ -231,43 +231,43 @@ If a provider-client record does not exist yet, `BeanImageProvider` can lazily r
 
 ## Operational flows
 
-## Upload-token + multipart upload
+## Authenticated multipart upload
 
-The tokened upload flow is the most important request path.
+Ordinary image upload is one authenticated multipart request:
 
-The flow is:
-
-1. call `POST /image/upload-token`
-2. Vona resolves the image scene and validates the declared `size` and `mimeType`
-3. Vona issues a temporary upload token that is bound to the upload path
-4. submit `POST /image/upload` as multipart form data
-5. send:
-   - `token`
+1. submit `POST /image/upload` as multipart form data
+2. send:
+   - `imageScene`
    - `image`
-6. the controller verifies the token, re-checks file size, MIME type, and extension, then uploads through the resolved provider
+3. Vona reads the received file's actual size and MIME type
+4. Vona resolves the image scene, provider, visibility, and metadata server-side
+5. Vona validates actual size, MIME type, and extension against the scene policy, then uploads through the resolved provider
 
 Representative controller shape:
 
 ```typescript
-@Web.post('upload-token')
-async createUploadToken(@Arg.body() data: DtoImageUploadTokenRequest) {
-  return await this.bean.imageUploadPolicy.createUploadToken(data);
-}
-
 @Web.post('upload')
-@Core.fileUpload()
+@Core.fileUpload({
+  busboy: {
+    limits: { fields: 1, files: 1, parts: 3 },
+  },
+})
 @Api.contentType('application/json')
-async upload(@Arg.field('token') token: string, @Arg.file('image') file: IUploadFile) {
-  const payload = await this.bean.imageUploadPolicy.verifyUploadToken(
-    token,
-    this.ctx.route.routePathRaw,
-  );
-  await this._validateUploadFile(file, payload);
+async upload(
+  @Arg.field('imageScene', v.required(), z.string()) imageScene: string,
+  @Arg.file('image', v.required()) file: IUploadFile,
+) {
+  const policy = await this.bean.imageUploadPolicy.resolveUploadPolicy({
+    imageScene,
+    size: (await fse.stat(file.file)).size,
+    mimeType: file.info.mimeType,
+  });
+  await this.bean.imageUploadPolicy.validateUploadFile(...);
   return await this.bean.image.upload(...);
 }
 ```
 
-This flow reuses the normal Vona upload model from [Upload Guide](/backend/upload-guide), but adds image-scene policy and a path-bound temporary token.
+The normal passport guard remains the authorization boundary. Temporary tokens are still used for signed delivery where needed, but ordinary image upload does not issue or accept an upload token.
 
 ## Direct upload
 
@@ -279,14 +279,13 @@ The shared flow is:
 2. call `app.bean.image.createDirectUpload(...)`
 3. let the provider create the direct-upload resource
 4. persist the draft image record
-5. return provider information plus `uploadUrl`
+5. return the public direct-upload session: Cabloy image `id`, provider-hosted `uploadUrl`, and optional presentation fields
 6. upload bytes to the returned `uploadUrl`
-7. finalize through `POST /image/direct-upload/finalize`
+7. finalize through `POST /image/direct-upload/finalize` using the Cabloy image `id`; the finalized response has the normal public image action shape
 
-The built-in providers currently support this flow in two different ways:
+The built-in Cloudflare provider supports this flow by returning a provider-hosted upload target.
 
-- `image-cloudflare:cloudflare` returns a provider-hosted upload target
-- `image-native:native` returns an app-local upload target under `/image-native/direct-upload/:resourceId`, stores the uploaded bytes as a draft file, and promotes that draft into the final native storage path during finalize
+The native provider does not support direct upload and should use the standard authenticated `/image/upload` flow instead.
 
 That provider difference is exactly why the shared API keeps direct upload split into create-upload-target and finalize steps.
 
@@ -310,12 +309,12 @@ The native provider does not implement `uploadUrl`.
 
 When delivery is signed and the provider uses proxy delivery, `BeanImage.getVariantUrl(...)` creates a temporary delivery token and returns a local delivery URL such as:
 
-- `/image/delivery/:imageId?token=...`
+- `/image/delivery?imageId=...&token=...`
 
 The delivery controller then:
 
-1. verifies the delivery token against the request path
-2. confirms the token image ID matches the request image ID
+1. verifies the delivery token against the fixed delivery endpoint path
+2. confirms the token image ID matches the request `imageId` query value
 3. redirects to the final target URL
 
 This is why native signed delivery behaves differently from Cloudflare signed delivery.
@@ -348,7 +347,7 @@ Practical behavior to know:
 
 - it defaults to proxy-signed delivery
 - it can return local static URLs under `/api/static/...`
-- it supports direct upload through an app-local upload target plus shared finalize
+- it does not support direct upload and uses the standard authenticated multipart upload flow
 - named variants produce stable variant files such as `__thumbnail`
 - ad hoc transforms produce stable hashed files such as `__t_<hash>`
 - repeated requests for the same custom transform reuse the same cached transformed output
@@ -489,7 +488,7 @@ A practical sequence is:
 1. create the scene bean
 2. define `upload` rules and optional provider/meta resolvers
 3. point entity or DTO metadata at the new scene name
-4. verify upload-token and serializer behavior end to end
+4. verify authenticated multipart upload and serializer behavior end to end
 
 ## Add a new image provider
 
@@ -508,8 +507,9 @@ A practical provider checklist is:
 
 1. implement the required methods
 2. decide whether to support `uploadUrl`, `createDirectUpload`, and `download`
-3. define sensible base options in the decorator
-4. verify variant URL behavior, signed delivery behavior, and delete behavior
+3. only implement `createDirectUpload` when the provider can hand the client a real external upload target instead of routing bytes back through the local app
+4. define sensible base options in the decorator
+5. verify variant URL behavior, signed delivery behavior, and delete behavior
 
 ## Test-backed reading map
 
@@ -519,8 +519,8 @@ The current repo already contains strong executable examples under:
 
 The most useful tests are:
 
-- `imageUpload.test.ts` for upload-token, upload, direct-upload, and upload-url request flows
-- `imageNative.test.ts` for local upload, native direct-upload/finalize, variant URLs, signed delivery, and delete behavior
+- `imageUpload.test.ts` for authenticated multipart upload, native direct-upload rejection, Cloudflare direct-upload, and upload-url request flows
+- `imageNative.test.ts` for local upload, variant URLs, signed delivery, and delete behavior
 - `imageCloudflareMapping.test.ts` for Cloudflare mapping, custom transforms, signed delivery, direct upload, and upload-by-URL behavior
 
 When the source and a prose explanation seem to disagree, prefer the current source and tests.

package/cabloy-docs/backend/jwt-guide.md

@@ -180,6 +180,27 @@ const accessToken = await this.bean.jwt.createTempAuthToken({ userId: '1' });
 
 This is useful when a token should remain valid only briefly, for example for URL-bound handoff flows.
 
+### Design rule: bind temporary auth to one exact endpoint
+
+A temporary auth token can optionally bind to one exact API pathname. Keep that binding strict: do not introduce prefix or wildcard path matching merely because a browser-facing endpoint has a resource ID in its route path.
+
+When one temporary passport token must authorize several resource URLs in the same delivery capability, define a fixed endpoint path and move the resource identity to a validated query parameter:
+
+```text
+GET /api/file/download?fileId=123
+GET /api/image/delivery?imageId=456
+```
+
+The temporary passport token can then bind exactly to `/api/file/download` or `/api/image/delivery`. It authorizes the caller at the delivery-endpoint level, not at the individual-resource level.
+
+Resource authorization must remain separate and explicit. A signed delivery token should carry the file/image ID, and the controller must compare that signed ID with the validated `fileId` or `imageId` query value. For image transformations, continue taking authorization-relevant variant options from the signed payload rather than from mutable query input.
+
+This separation keeps the token primitive generic and auditable:
+
+- exact pathname binding scopes the temporary passport token to one endpoint
+- signed payload claims scope the delivery token to its resource, audience, and any protected representation options
+- query parameters carry request identity without expanding temporary-token path authority
+
 ## Verification
 
 JWT verification can happen directly through a client:

package/cabloy-docs/frontend/file-guide.md

@@ -0,0 +1,147 @@
+# File Guide
+
+This guide explains the Zova `basic-file` contract in Cabloy Basic. It is a metadata-driven, relation-backed field: the backend defines a file scene, the business field persists IDs, and DTO relations supply completed-file display and delivery data.
+
+> Read this with [Backend File Guide](/backend/file-guide) and [Fullstack File Workflow](/fullstack/file-workflow). For the surrounding Zova architecture, see the [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap) and [Zova Source Reading Map](/frontend/zova-source-reading-map).
+
+## Persisted IDs and resolved relations
+
+The primary form value is a file ID, never a storage URL:
+
+| Shape            | Contract                                                                |
+| ---------------- | ----------------------------------------------------------------------- |
+| Single file      | `TableIdentity`; an empty field is `''`                                 |
+| Multiple files   | `TableIdentity[]`                                                       |
+| Display relation | DTO-resolved `DtoFileView` data, such as `dossierFiles?: DtoFileView[]` |
+
+`IFilePreviewItem` is an internal `basic-file` display-normalization shape. It is not a public backend DTO contract. Persist IDs and expose a `DtoFileView` relation for rendering.
+
+The training-record example aligns one scene, ID field, and relation name:
+
+```ts
+// EntityRecord: persisted field and resource renderers
+@Api.field(
+  ZovaRender.field('basic-file:formFieldFile', {
+    fileScene: 'training-record:dossierFile',
+    relationName: 'dossierFiles',
+    maxCount: 3,
+  }),
+  ZovaRender.cell('basic-file:file', { relationName: 'dossierFiles' }),
+  v.array(v.tableIdentity()),
+)
+dossierFileIds?: TableIdentity[];
+
+// DtoRecordView: consumer projection
+@Api.field(
+  v.optional(),
+  v.serializerTransform('a-file:resolveViews', {
+    fieldName: 'dossierFileIds',
+    fileScene: 'training-record:dossierFile',
+  }),
+  v.array(DtoFileView),
+)
+dossierFiles?: DtoFileView[];
+```
+
+The default naming convention maps `fooId` to `foo` and `fooIds` to `foos`. This inference is mechanical; provide `relationName` when the business name differs.
+
+## Built-in resources
+
+- `basic-file:formFieldFile` manages browser selection, local checks, transport selection, completed-file cards, and form/relation synchronization.
+- `basic-file:file` renders a resolved relation in a table.
+- `ModelFile` owns shared upload-policy query state. The field controller owns only interaction and upload state.
+
+The table cell does not resolve metadata from IDs. With one resolved item it renders a download link; with several it displays the first filename and a `+N` selection surface. Without a resolved relation it can only fall back to the raw cell value.
+
+## Configure `basic-file:formFieldFile`
+
+`fileScene` has an optional TypeScript type but is operationally required before a user can select/upload a file.
+
+| Option         | Purpose and precedence                                                                             |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| `fileScene`    | Required backend scene for policy lookup and upload.                                               |
+| `relationName` | Explicit resolved-relation field; otherwise infer `fooId → foo` or `fooIds → foos`.                |
+| `multiple`     | Local override; otherwise uses scene policy.                                                       |
+| `maxCount`     | Frontend-only retained-item limit. Defaults to `1`; single mode is always one.                     |
+| `accept`       | Browser accept string or tokens. When present, it overrides composed MIME/extension accept values. |
+| `mimeTypes`    | Local client restriction; falls back to scene policy when omitted.                                 |
+| `extensions`   | Local client restriction; falls back to scene policy when omitted.                                 |
+| `maxSize`      | Local client maximum; falls back to scene policy when omitted.                                     |
+| `minSize`      | Frontend-only minimum size.                                                                        |
+| `placeholder`  | Empty-field text.                                                                                  |
+
+For composed browser acceptance, explicit `accept` wins. Otherwise local MIME types and extensions are used by category, falling back to policy values for omitted categories. The server always validates the real upload; browser validation is UX, not a security or storage boundary.
+
+A scene can publish `multiple: true` while the field still retains only one item: set `maxCount` above `1` when the UI should allow multiple files.
+
+## Model-owned policy state
+
+`ModelFile.getUploadPolicy(fileScene)` creates scene-keyed `$useStateData(...)` state using `['uploadPolicy', 'file', fileScene]` and `disableSuspenseOnInit: true`.
+
+Rendering establishes this query without suspending the initial form. The upload button is disabled while a real scene policy is pending. At the file-selection boundary, the controller calls `$QueryEnsureLoaded(...)` before it chooses cardinality, checks policy-backed constraints, or selects a transport. Fields with the same scene reuse the same model-owned policy state.
+
+## Upload behavior
+
+### Ordinary scenes
+
+When policy does not advertise direct upload, the field uses the generated API action:
+
+```ts
+await scope.api.file.upload({ fileScene, file });
+```
+
+This is one authenticated multipart request. The completed response is ready, so the field updates its ID value and resolved relation together.
+
+### Direct-capable scenes
+
+When policy publishes `directUpload: true`, the field performs:
+
+```text
+create target
+→ raw File fetch using returned method and headers
+→ finalize through Cabloy
+→ update form state from finalized response
+```
+
+The browser branches only on `directUpload`, never on provider identity. It sends raw `File` bytes with the returned method and headers; current R2 targets use `PUT`. Do not add Cabloy credentials, cookies, or guessed headers to the provider request. Provider CORS must allow the frontend origin, method, and returned headers.
+
+The component supports raw-body `PUT`/`POST` targets, not HTML-form/presigned-POST field protocols. It intentionally has no progress reporting, cancellation, retry, timeout, parallel transfer, or rollback UI. A direct draft ID never enters the ID field or relation; only the final ready response does.
+
+`ApiFile.uploadUrl()` exists for authorized custom consumers. `basic-file:formFieldFile` has no remote URL-import UI and never fetches a remote URL itself.
+
+## Relation synchronization and batch behavior
+
+After a ready ordinary upload or ready direct finalization, the controller rebuilds the ID value and relation in the same form operation. It keeps resolved data already supplied by the DTO, merges newly returned upload data, and uses an ID-only fallback only when metadata is unavailable.
+
+Removing an item changes form state only. It does not call a file-delete API or remove stored provider content.
+
+Multiple selected files are processed sequentially and are not transactional:
+
+- local validation failures can be skipped while later files continue;
+- a thrown upload or finalization failure prevents the current batch from committing its new IDs to the form;
+- an earlier successfully stored file is not automatically rolled back if a later file fails;
+- failed direct transfers/finalizations can leave a backend draft or object for lifecycle cleanup.
+
+Do not describe the form-state boundary as a storage rollback guarantee.
+
+## Delivery and SSR
+
+Render the resolved `downloadUrl`; never derive a provider URL from an ID, bucket, or storage key. `basic-file` prefixes a relative `/api/...` URL with configured `api.baseURL`; absolute CDN and provider-signed URLs pass through unchanged.
+
+For a private Admin relation that the backend resolves with `deliveryOptions.audience: true`, the browser adds a short-lived, path-scoped passport code only when the user opens a download. The code is model-owned, shared by the current user for the file-download route family, and is not written back into the DTO URL. The delivery URL also remains resource-bound, so the code cannot authorize a different file. SSR never requests or serializes this passport code.
+
+The hidden native file input is inside `ClientOnly`. Existing relation cards and raw download anchors can render during SSR, but file selection, direct provider transfer, and user-bound download URL decoration are browser-only. Policy lookup itself is model-owned rather than wrapped in `ClientOnly`, while the selection boundary waits for strict policy readiness.
+
+## File UI remains file-specific
+
+The field presents filename, content type, human-readable size, upload time, download, and removal. It intentionally does not inherit image crop, resize, thumbnail, gallery, variant, or transform behavior.
+
+## Frontend checklist
+
+1. Define the backend `fileScene` before configuring the field.
+2. Persist ID values and expose matching `DtoFileView` relations.
+3. Keep `relationName`, persisted field, serializer transform, and scene name aligned.
+4. Let `ModelFile` own policy state and branch only on semantic policy capability.
+5. Configure `maxCount` explicitly for multi-file UI.
+6. Update IDs/relations only from ready/finalized responses.
+7. Render resolved `downloadUrl` values rather than storage-derived paths.

package/cabloy-docs/frontend/image-guide.md

@@ -7,7 +7,7 @@ Zova image is not only a file input. It is a frontend image layer built around:
 - the built-in form-field renderer `basic-image:formFieldImage`
 - the built-in table-cell renderer `basic-image:image`
 - resolved relation fields such as `image` and `sceneImages`
-- upload-token based upload through the generated image API
+- policy-selected ordinary or provider-hosted direct upload through the generated image API
 - optional crop and resize behavior in the browser
 - shared preview dialogs for form and table usage
 
@@ -58,7 +58,7 @@ Use this as the standard image field renderer for forms.
 It supports:
 
 - single-image and multi-image fields
-- upload-token based upload
+- policy-selected ordinary or direct upload
 - frontend file validation
 - optional crop
 - optional resize and re-encode before upload
@@ -121,9 +121,9 @@ v.serializerTransform('a-image:resolveView', {
 A practical rule is:
 
 - frontend validation, crop, and resize improve UX
-- backend image scenes and backend upload-token verification remain the true policy boundary
+- backend image scenes and authenticated multipart validation remain the true policy boundary
 
-For the backend side of that contract, read [Backend Image Guide](/backend/image-guide), especially the sections on image scenes, upload-token flow, and DTO-side image view resolution.
+For the backend side of that contract, read [Backend Image Guide](/backend/image-guide), especially the sections on image scenes, authenticated multipart upload, and DTO-side image view resolution.
 
 ## One running example through this guide: Student image
 
@@ -316,12 +316,15 @@ The built-in form field follows a consistent frontend flow.
 2. the frontend validates the file type and size
 3. if enabled, the crop dialog opens
 4. if configured, the browser resizes and re-encodes the image
-5. the frontend calls `scope.api.image.createUploadToken(...)`
-6. the frontend uploads multipart data with `token` and `image`
-7. the stored field value is updated to the uploaded image ID or image ID array
-8. the resolved relation field is synchronized so the form can preview the uploaded image immediately
+5. the frontend reads the server-provided upload-policy capability
+6. ordinary scenes call `scope.api.image.upload(...)` with multipart `imageScene` and `image`
+7. direct-capable scenes call `scope.api.image.createDirectUpload(...)`, upload multipart data to the returned provider URL without Cabloy credentials, then call `scope.api.image.finalizeDirectUpload(...)`
+8. the stored field value is updated from the ordinary upload response or the finalized direct-upload response
+9. the resolved relation field is synchronized so the form can preview the completed image immediately
 
-That last step is easy to miss, but it is one of the most important behaviors in the current implementation.
+The frontend does not select a provider by name. Vona resolves the scene and publishes only whether direct upload is available. A direct-upload draft ID is not written to the form until finalization succeeds.
+
+That finalization boundary is easy to miss, but it is one of the most important behaviors in the current implementation.
 
 The field value stores IDs.
 
@@ -348,6 +351,12 @@ In readonly mode, the field still renders preview cards.
 
 If no images are available, it shows a lightweight empty-state message instead of a file input.
 
+### Private Admin delivery
+
+For a private Admin relation resolved with `deliveryOptions.audience: true`, the client obtains a short-lived passport code after hydration and appends it only to the Cabloy image delivery URL. The code is held in the passport model's in-memory, route-scoped cache and is never written into the resolved relation, SSR HTML, or dehydrated state. The backend still verifies the resource-bound delivery token and the issuing user, so another authenticated user cannot reuse a copied URL.
+
+User-bound delivery forces the Cabloy proxy path. A provider redirect after Cabloy authorization can still expose a separate short-lived provider URL; use a streaming proxy when that remaining provider-link window is unacceptable.
+
 ### Preview dialog
 
 When an image preview is available, the field opens a shared preview dialog that supports:

package/cabloy-docs/frontend/model-state-guide.md

@@ -112,6 +112,18 @@ findAll() {
 }
 ```
 
+### Query readiness utilities: loaded versus fresh
+
+These utilities consume an existing model-owned `$useStateData(...)` query. They do not create another state category or a second fetch lifecycle:
+
+- `$QueryEnsureLoaded(...)` is an availability utility. It waits only when the query has no `data`, then returns the query wrapper.
+- `$QueryGetFresh(...)` is a non-blocking freshness read. It returns data only when a model-supplied `isStale(query)` predicate accepts the cached value; otherwise it starts refresh work and returns `undefined` for the current render.
+- `$QueryEnsureFresh(...)` is an awaited freshness gate. It waits for stale data to refresh, returns the result, and propagates query errors.
+
+The freshness predicate belongs to the domain owner. For example, `ModelPassport` considers a temporary token stale when it is absent or when its `dataUpdatedAt` falls outside the model's short reuse window.
+
+For render-versus-interaction placement guidance, see [`$useStateData` Best Practices](/frontend/use-state-data-best-practices).
+
 ## 2. `$useMutationData(...)`
 
 Use this for model-owned mutation state.