cabloy 5.1.102 → 5.1.104

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-architecture.md

@@ -129,7 +129,7 @@ The `a-model` source exposes five main state families through `BeanModelBase` he
 - `mem` → in-memory state through `$useStateMem(...)`
 - `local` → local-storage state through `$useStateLocal(...)`
 - `cookie` → cookie-backed state through `$useStateCookie(...)`
-- `db` → async persisted state through `$useStateDb(...)`
+- `db` → async persisted state through `$useStateLocalAsync(...)`
 
 This is why Zova Model is better understood as a **unified model-state layer** rather than only a remote-data wrapper.
 

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

@@ -86,7 +86,34 @@ The important point is architectural:
 
 ## The main helper families
 
-The current source organizes model state around these helper families.
+The current source organizes model state around these helper families. They share model-owned query-key and cache infrastructure, but differ in the surface returned to callers and in their persistence and restore lifecycle.
+
+### Choose the state helper by ownership and lifecycle
+
+Choose a helper by the state surface, persistence, restore, and SSR behavior it needs, not only by whether its value should survive a reload.
+
+| Helper                     | Use it when                                                                       | Caller-facing surface                                                     | Persistence and restore                                                                      |
+| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `$useStateData(...)`       | The model owns remote or query-style async state and consumers need query status  | Full query wrapper, including `data`, `error`, and readiness/status state | Normal query lifecycle; may participate in query hydration subject to metadata               |
+| `$useStateMem(...)`        | The model owns reusable runtime state without a browser persistence backend       | Assignable state value                                                    | No browser persistence; eligible successful state can transfer through initial SSR hydration |
+| `$useStateLocal(...)`      | The model owns a small browser value that should restore synchronously            | Assignable state value                                                    | Synchronous `localStorage` restore                                                           |
+| `$useStateCookie(...)`     | The state needs cookie persistence or request-aware handling                      | Assignable state value                                                    | Synchronous cookie restore                                                                   |
+| `$useStateLocalAsync(...)` | The model owns longer-lived browser-local state whose restore may be asynchronous | Assignable state value                                                    | Asynchronous `localforage` restore                                                           |
+| `$useStateComputed(...)`   | The model exposes derived state                                                   | Computed value                                                            | No query fetch or persistence                                                                |
+
+### Data, local, and async-local behavior
+
+`$useStateData(...)`, `$useStateLocal(...)`, and `$useStateLocalAsync(...)` use the same model-owned cache foundation, but they are not interchangeable.
+
+| Concern              | `$useStateData(...)`                                      | `$useStateLocal(...)`                                         | `$useStateLocalAsync(...)`                                                                            |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Return surface       | A memoized query wrapper                                  | An assignable state value                                     | An assignable state value                                                                             |
+| Source or storage    | `queryFn`, query cache, and query configuration           | `localStorage`                                                | `localforage`                                                                                         |
+| Initial availability | Follows the query lifecycle                               | Restores synchronously, then falls back to `meta.defaultData` | Restores asynchronously, then falls back to `meta.defaultData`                                        |
+| Intended write flow  | Mutation, cache update, and invalidation policy           | Replace or assign the model field                             | Replace or assign the model field                                                                     |
+| SSR behavior         | Can follow ordinary query dehydration and hydration rules | Browser storage is unavailable on the server                  | Browser storage is unavailable on the server and async-local state explicitly opts out of dehydration |
+
+Use the detailed [`$useStateData` Best Practices](/frontend/use-state-data-best-practices) guide for render-versus-interaction placement, `disableSuspenseOnInit`, freshness utilities, and explicit readiness boundaries.
 
 ### 1. `$useStateData(...)`
 
@@ -112,6 +139,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.
@@ -143,16 +182,62 @@ The pattern to notice is that the model owns both the mutation and the follow-up
 
 ## 3. `$useStateMem(...)`
 
-Use this when the state should stay only in memory.
+Use this for reusable runtime state that belongs to a Model but does not need a browser persistence backend. It returns an assignable value, rather than a query wrapper, while retaining Model-owned Query Cache identity.
 
 Current-source characteristics:
 
-- no persistence
-- `enabled: false`
+- `enabled: false`, so it does not define a normal remote-fetch lifecycle
 - `staleTime: Infinity`
-- still uses model-owned query cache semantics under the hood
+- `meta.persister: false`, so it does not read or write `localStorage`, cookies, or `localforage`
+- reads from existing Query Cache first, then `meta.defaultData`, then `undefined`
+- assignments update the Query Cache without a persister save
+- automatic key prefixing isolates the state by Model identity and, when enabled, selector identity
+
+This is useful when several consumers or Model methods need the same business state during the current frontend runtime, but the browser should not restore it from storage. For structured values, replace or assign the Model field so its custom-ref setter updates the Query Cache:
+
+```typescript
+this.selectedIds = nextSelectedIds;
+```
+
+A plain Controller field is usually clearer when the state belongs only to that one Controller. Choose `$useStateLocal(...)`, `$useStateCookie(...)`, or `$useStateLocalAsync(...)` when browser persistence is part of the requirement. Choose `$useStateData(...)` when consumers need query status, errors, freshness, or a remote-fetch lifecycle.
+
+### SSR transfer is not persistence
+
+`meta.persister: false` means no browser persistence backend. It does not, by itself, exclude the state from the initial SSR server-to-client Query Cache handoff.
+
+After server rendering, a successful eligible memory-state query can be dehydrated with the shared Query Cache. During client SSR pre-hydration, the snapshot is hydrated into the client QueryClient. A later `$useStateMem(...)` read can therefore receive the transferred value directly from cache when its effective key matches: the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`.
+
+This transfer has limits:
+
+- it applies only to entries accepted by the normal dehydration policy; `meta.ssr.dehydrate: false` opts a state out
+- it is not a replacement for `localStorage`, cookies, or async-local persistence
+- it does not make the value survive a later browser reload without a new SSR handoff
+- it does not make an empty or unsuccessful cache entry transfer automatically
+
+The router-tabs Model uses memory state for current navigation keys and for tabs when tab caching is disabled. The page-data Model uses memory slots keyed by page path. Read [SSR Init Data](/frontend/ssr-init-data) for the page-side flow, or [A-Model Under the Hood](/frontend/a-model-under-the-hood) for the Query Cache and dehydration mechanics.
+
+### SSR/CSR bridge: `ModelPassport`
 
-This is useful when you want model ownership and query-key identity without local persistence.
+`ModelPassport` shows that the state helper selected on the server and the one selected on the client do not have to be the same. Its application initialization creates the same logical state differently by environment:
+
+```typescript
+this.passport = process.env.CLIENT
+  ? this.$useStateLocal({ queryKey: ['passport'] })
+  : this.$useStateMem({ queryKey: ['passport'] });
+```
+
+On the SSR server, authenticated work can assign the current passport to the memory-backed Query Cache entry. If that entry is successful and eligible, it is dehydrated with the server QueryClient. During client SSR pre-hydration, the snapshot restores the entry before the client Model consumes it.
+
+The client then creates a `$useStateLocal(...)` wrapper for the same effective key. Its read order is Query Cache first, then `localStorage`, then `meta.defaultData`. The hydrated server passport therefore wins on the initial client read; synchronous local-storage restoration is a fallback only when the transferred cache entry is absent.
+
+This gives authentication state two complementary properties:
+
+- SSR uses the request-confirmed passport to keep the initial HTML and client hydration consistent.
+- CSR-only entry and later browser sessions can restore the client-local passport value from `localStorage`.
+
+The server `$useStateMem(...)` entry is the entry that is dehydrated. The client `$useStateLocal(...)` call is a new client-side wrapper that reuses hydrated cache because its effective key matches. Matching requires the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`; the short logical key alone is not global identity.
+
+Reading the hydrated value does not save it back to `localStorage`. A later assignment through the client local-state wrapper updates Query Cache and writes the local-storage record. This is an initial SSR cache handoff plus client persistence fallback, not automatic persistence of the SSR snapshot.
 
 ## 4. `$useStateLocal(...)`
 
@@ -183,9 +268,9 @@ Current-source characteristics:
 
 This is particularly relevant for state that must participate in request-aware or SSR-adjacent flows.
 
-## 6. `$useStateDb(...)`
+## 6. `$useStateLocalAsync(...)`
 
-Use this when the model state should persist asynchronously in db-style client storage.
+Use this when the model state should persist asynchronously in browser-local storage backed by `localforage`.
 
 Current-source characteristics:
 
@@ -193,10 +278,40 @@ Current-source characteristics:
 - `enabled: false`
 - `staleTime: Infinity`
 - explicit `ssr.dehydrate = false`
-- getters may need async restore flow before data is available
+- the first unresolved read may need async restore before the state is available
 
 This is useful for larger persisted client state that should outlive a page session without being stored in cookies or plain local storage.
 
+### Initialize and ensure async-local state
+
+Assign the state property before awaiting it. When later initialization depends on the restored value, establish an explicit restore boundary with `$ensureStateLocalAsync(...)`. It waits for the pending initial restore to settle; it does not force another load and does not guarantee a defined result:
+
+```typescript
+protected async __init__() {
+  this.tabs = this.$useStateLocalAsync({
+    queryKey: ['tabs'],
+    meta: {
+      defaultData: [],
+    },
+  });
+
+  await this.$ensureStateLocalAsync(this.tabs);
+
+  // Continue only after persisted tabs, or the fallback default, is available.
+  this.initializeTabs();
+}
+```
+
+`meta.defaultData` is a fallback: it initializes the state only when no persisted value is restored. If neither provides a value, the ensured result can still be `undefined`. The router-tabs model follows this assign-then-ensure sequence before it continues with route initialization.
+
+Persisted local and async-local state should be updated by replacing or assigning the model field so its custom-ref setter can update query state and persist the new value:
+
+```typescript
+this.tabs = nextTabs;
+```
+
+Do not rely on an in-place nested mutation alone to persist the change. Assigning `undefined` removes the persisted value.
+
 ## 7. `$useStateComputed(...)`
 
 Use this when the model should expose derived state that is still model-key-oriented but computed locally.
@@ -240,16 +355,17 @@ Model state choices can affect SSR behavior.
 
 Current-source behaviors to remember:
 
-- query state can be dehydrated on server and hydrated on client
+- successful eligible Query Cache state can be dehydrated on the server and hydrated on the client
+- `$useStateMem(...)` has no browser persister but can participate in that initial SSR handoff unless excluded by metadata
 - mutations are not dehydrated
-- `db` state is explicitly not dehydrated
-- server cannot use local-storage or db persistence backends
-- cookie state is special because cookie access can still exist through the app cookie surface
+- `$useStateLocalAsync(...)` explicitly opts out of dehydration
+- server-side sync local and cookie persister-backed Query Cache entries are excluded by the default dehydration policy; this does not prevent a client `$useStateLocal(...)` or `$useStateCookie(...)` wrapper from reusing a hydrated entry that the server created with a different eligible helper
+- server cannot use local-storage or async-local persistence backends; cookie state is special because cookie access can still exist through the app cookie surface
 
 Practical implication:
 
-- do not assume every persisted model state behaves the same during SSR
-- choose `mem`, `local`, `cookie`, `db`, or `data` based on ownership and hydration requirements, not only convenience
+- do not equate browser persistence with SSR transfer, or assume every state family behaves the same during SSR
+- choose `mem`, `local`, `cookie`, `localAsync`, or `data` based on ownership, persistence, and hydration requirements, not only convenience
 
 ## Real examples to read
 
@@ -277,7 +393,7 @@ This file shows:
 
 - `@Model({ enableSelector: true, ... })`
 - richer model initialization in `__init__`
-- mixed use of `$useStateMem(...)` and `$useStateDb(...)`
+- mixed use of `$useStateMem(...)` and `$useStateLocalAsync(...)`
 - model-owned tab state with cache and persistence decisions
 
 ### SSR-sensitive auth model

package/cabloy-docs/frontend/ssr-init-data.md

@@ -31,7 +31,18 @@ export class ControllerPageTodo {
 1. a model bean encapsulates the data access path
 2. the controller injects the model
 3. `__init__` prepares the data on the server
-4. model-based SSR support synchronizes that data to the client and completes hydration automatically
+4. successful eligible Query Cache state is captured in the SSR handoff
+5. client SSR pre-hydration restores that cache before the client model consumes it
+
+## What hydration reuses
+
+The initial SSR handoff reuses model Query Cache data, not only `$useStateData(...)` results. A successful eligible `$useStateMem(...)` value can also transfer from the server to the initial client runtime even though it has no browser persistence backend.
+
+Client reuse requires the model call to resolve to the same effective query key: Zova prefixes the logical key with Model identity and, for selector-enabled models, selector identity. State marked with `meta.ssr.dehydrate: false` is excluded. This handoff does not make memory state durable across a later browser reload, and it does not guarantee that every client query avoids fetching.
+
+`ModelPassport` is a concrete SSR/CSR bridge: the server creates `passport` with `$useStateMem({ queryKey: ['passport'] })`, while the client creates `$useStateLocal({ queryKey: ['passport'] })`. The successful eligible server memory entry is what SSR transfers. Because the client local-state wrapper reads Query Cache before `localStorage`, the hydrated passport supplies the initial client value when the effective key matches. If no transferred entry exists, `$useStateLocal(...)` can instead restore its browser-local value. Hydration alone does not save the transferred value to `localStorage`; later client-side assignments do.
+
+For helper selection and the complete passport flow, read [Model State Guide](/frontend/model-state-guide). For the dehydration filter and QueryClient lifecycle, read [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
 ## Implementation checks for SSR data-loading changes
 

package/cabloy-docs/frontend/use-state-data-best-practices.md

@@ -220,6 +220,60 @@ The better middle ground is:
 
 That is very different from rebuilding a second fetch lifecycle.
 
+### Choose the wait semantic: loaded versus fresh
+
+Waiting for an existing query can mean two different things:
+
+- **Loaded** means a value exists.
+  `$QueryEnsureLoaded(...)` waits only when `query.data === undefined`, so it can continue with an older cached value.
+- **Fresh** means the model's domain-specific validity rule accepts the value.
+  `$QueryGetFresh(...)` and `$QueryEnsureFresh(...)` receive an `isStale(query)` predicate, so the model decides whether loaded data is still safe to consume.
+
+| Need                                 | Helper                          | Missing or stale behavior                                                | Return shape                |
+| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------ | --------------------------- |
+| An interaction needs any loaded data | `await $QueryEnsureLoaded(...)` | Waits only while `query.data === undefined`                              | Query object or `undefined` |
+| Render may consume only fresh data   | `$QueryGetFresh(...)`           | Starts `query.suspense()` and returns no data for the current render     | `TData \| undefined`        |
+| An interaction requires fresh data   | `await $QueryEnsureFresh(...)`  | Waits for `query.suspense()` and throws a query error when refresh fails | `TData \| undefined`        |
+
+Loaded is an availability condition. Fresh is a validity condition defined by the model; it might use `dataUpdatedAt`, response expiry metadata, or another business rule. `a-model` accepts the predicate and does not prescribe that policy.
+
+For example, `ModelPassport` keeps the temporary-token query and its 30-second reuse rule in the model, while the generic helpers provide the consumption mechanics:
+
+```ts
+import { $QueryEnsureFresh, $QueryGetFresh, BeanModelBase, Model } from 'zova-module-a-model';
+
+@Model()
+export class ModelPassport extends BeanModelBase {
+  getFreshTempAuthToken(options: TempTokenOptions): string | undefined {
+    return $QueryGetFresh(
+      () => this.getTempAuthToken(options),
+      query => this._isTempAuthTokenExpired(query.data, query.dataUpdatedAt, options.staleTime),
+    );
+  }
+
+  async ensureFreshTempAuthToken(options: TempTokenOptions): Promise<string | undefined> {
+    return await $QueryEnsureFresh(
+      () => this.getTempAuthToken(options),
+      query => this._isTempAuthTokenExpired(query.data, query.dataUpdatedAt, options.staleTime),
+    );
+  }
+}
+```
+
+Use the non-blocking facade during render, where stale data should not build a protected URL:
+
+```ts
+const passportCode = this.$passport.getFreshTempAuthToken(options);
+```
+
+Use the awaited facade at an interaction boundary, where a download or preview must not continue with an expired token:
+
+```ts
+const passportCode = await this.$passport.ensureFreshTempAuthToken(options);
+```
+
+Both paths reuse the same model-owned query. When `$QueryGetFresh(...)` finds stale data, it starts `query.suspense()` and returns `undefined` for the current render; reactive query state provides the replacement value on a later render. `$QueryEnsureFresh(...)` instead waits for that refresh and propagates query errors to the interaction flow.
+
 ## Practical rule 7: derive render-time state once per render when possible
 
 Even when the query object is reused, a controller can still become noisy if it repeatedly derives the same values in several helper calls.

package/cabloy-docs/fullstack/file-workflow.md

@@ -0,0 +1,135 @@
+# Fullstack File Workflow
+
+This page follows a Cabloy Basic file field from Vona contract truth to Zova interaction. It is the forward contract loop for `a-file` and `basic-file`.
+
+> Read this with [Backend File Guide](/backend/file-guide), [Frontend File Guide](/frontend/file-guide), and [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## One business field, two consumer surfaces
+
+A file-backed business field persists IDs, while a DTO relation carries completed-file presentation data. The training-record module is the reference pattern:
+
+```ts
+// Vona scene: one trusted business capability
+@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 {}
+
+// Entity: persist only IDs and attach Zova 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[];
+
+// Consumer DTO: resolve completed display/delivery data
+@Api.field(
+  v.optional(),
+  v.serializerTransform('a-file:resolveViews', {
+    fieldName: 'dossierFileIds',
+    fileScene: 'training-record:dossierFile',
+  }),
+  v.array(DtoFileView),
+)
+dossierFiles?: DtoFileView[];
+```
+
+Keep the persisted field, resolved relation, `relationName`, and scene name aligned. `DtoFileView` is a consumer projection; it does not replace ID persistence. The serializer verifies the optional scene while resolving IDs, preventing a relation from silently consuming a file from another business capability.
+
+## Three ingestion paths and readiness
+
+### 1. Ordinary local upload
+
+```text
+Zova field
+→ authenticated POST /file/upload(fileScene, file)
+→ Vona validates received multipart file and resolves scene/provider
+→ provider storage
+→ ready action response
+→ ID field and relation update
+```
+
+The backend owns validation and storage. The response is ready immediately after backend storage; this is the portable Native-compatible path and needs no file upload token.
+
+### 2. Remote HTTPS URL import
+
+```text
+authorized server/API consumer
+→ POST /file/upload-url
+→ provider capability check
+→ secure HTTPS remote-fetch boundary
+→ provider storage
+→ ready action response
+```
+
+Remote import is not built into the browser field. It is a server/provider operation: the selected provider validates remote URL safety and actual content before storage. Native does not support this path; Cloudflare R2 does. A browser must not implement its own unrestricted remote fetch.
+
+### 3. Third-party direct upload
+
+```text
+policy.directUpload
+→ POST /file/direct-upload
+→ Cabloy draft + raw-body provider target
+→ browser transfers raw File without Cabloy credentials
+→ POST /file/direct-upload/finalize
+→ provider metadata verification + ready state
+→ ID field and relation update
+```
+
+A direct target is draft-only, not a completed file. Finalization is the only promotion to `ready`; drafts cannot resolve views, be downloaded, or enter business IDs/relations. The frontend uses returned method/headers for raw file transfer and stores only the finalized response.
+
+## Forward contract loop
+
+When a File contract changes, work from backend truth toward generated consumers:
+
+1. define or update the Vona `@FileScene`, persisted ID field, controller/DTO policy, and `a-file:resolveView(s)` relation;
+2. regenerate Vona metadata and inspect the emitted Swagger/OpenAPI contract;
+3. regenerate the filtered `basic-file` OpenAPI consumer;
+4. keep hand-authored Zova behavior in `ModelFile`, `ControllerFormFieldFile`, and `TableCellFile` thin and policy-driven;
+5. build the affected Admin and Web flavors, then run `npm run deps:vona` for the reverse dependency handoff.
+
+Generated contract outputs include:
+
+```text
+zova/.../basic-file/src/api/file.ts
+zova/.../basic-file/src/apiSchema/file.ts
+zova/.../basic-file/src/api/openapi/types.ts
+zova/.../basic-file/src/api/openapi/schemas.ts
+```
+
+Do not hand-edit these generated files. `ModelFile`, the form-field controller, the table cell, and Vona render metadata are hand-authored extension points.
+
+## Cross-layer invariants
+
+| Layer             | Owns                                                                                                     | Must not own                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Vona `a-file`     | scene policy, provider/client selection, actual validation, lifecycle, storage, visibility, and delivery | browser-controlled provider or storage choices                     |
+| DTO serializer    | safe `DtoFileView` projection and scene matching                                                         | persistence replacement or storage metadata disclosure             |
+| Zova `basic-file` | picker UX, local UX checks, policy-driven transport, ID/relation synchronization                         | provider selection, storage URL construction, or draft persistence |
+| Provider transfer | raw body transfer for a direct target                                                                    | Cabloy session credential forwarding                               |
+
+The frontend reads `downloadUrl` from a resolved view; it never constructs delivery URLs from IDs, buckets, or object keys. Upload-policy capability is semantic (`directUpload`), so frontend code never branches on provider identity.
+
+## Verification checklist
+
+For a File contract or workflow change, verify:
+
+1. the scene policy and persisted ID field match the intended business capability;
+2. create/view/list DTO schemas expose the matching `DtoFileView` relation and serializer transform;
+3. Swagger/OpenAPI contains the expected policy, multipart, direct-finalize, and URL-import actions;
+4. regenerated `basic-file` API/schema output is used rather than hand-patched;
+5. Native reports no direct/URL-import capability while the configured Cloudflare R2 scene advertises direct upload only when creation and finalization are both available;
+6. a draft cannot resolve a view or download URL, and the form updates only after finalization;
+7. private/public delivery still uses resolved URLs without leaking provider/storage data;
+8. run the affected Admin and Web builds and then `npm run deps:vona` after a generated frontend handoff.

package/cabloy-docs/fullstack/image-workflow.md

@@ -291,11 +291,20 @@ The form-side resource is responsible for:
 - selecting files
 - performing frontend validation
 - optionally cropping and resizing in the browser
-- requesting an upload token
-- uploading multipart data
-- binding the stored image ID field
+- selecting the policy-supported ordinary or direct upload transport
+- binding the finalized stored image ID field
+- synchronizing the relation preview only after upload completion
 - synchronizing the resolved relation field for immediate UI refresh
 
+### Upload transport selection
+
+The form field waits for the backend image-scene upload policy and selects one of two server-authorized paths:
+
+- ordinary scenes submit authenticated multipart `imageScene` and `image` data to Cabloy;
+- direct-capable scenes create a direct-upload session, send the image to the returned provider URL without Cabloy credentials, and finalize using the returned Cabloy image ID.
+
+The browser does not branch on provider identity. In both paths, it updates the stored ID field and resolved relation preview only after it has a completed image response; a direct-upload draft is never used as the form value.
+
 ### `basic-image:image`
 
 The table-side resource is responsible for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.102",
+  "version": "5.1.104",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.72",
+  "version": "5.1.73",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [