@@ -1,5 +1,95 @@
 # Changelog
 
+## [2.6.0] - 2026-08-13
+
+FuncToWeb moves onto `pytypehintweb 1.1.0`, and with it onto `pytypehint 1.0.0`.
+The annotation that marks a file parameter is now `FileHint`, and the division of
+labour around files is redrawn: the core stopped touching the filesystem, so
+everything that was a promise about the *real* file on disk — that it exists,
+that it is a file and not a directory, that its bytes fall between `min_size` and
+`max_size` — is now stated only where it is actually enforced. For FuncToWeb that
+is its own storage layer, which already did that work; nothing about uploads,
+references or the pending/promoted lifecycle is weaker than it was in 2.5.0.
+
+### Changed
+- **Breaking:** `IsPathFile` is replaced by `FileHint`, re-exported from
+  `func_to_web` with the same three fields (`extensions`, `min_size`,
+  `max_size`). This is a clean cut: there is no alias, no deprecation warning and
+  no support for `pytypehint 0.x`. Rename the import and the call —
+  `Annotated[str, IsPathFile(extensions=(".png",))]` becomes
+  `Annotated[str, FileHint(extensions=(".png",))]` — and nothing else changes.
+- **Breaking (behaviour):** `Signature.build()` no longer checks that a file
+  value exists, that it is a file, or how large it is. In 2.5.0 an invocation
+  carrying a path to a missing, oversized or undersized file was refused by the
+  layer below; in 2.6.0 the core only checks the **extension** of the value it is
+  given, and builds the arguments.
+- **Breaking (behaviour):** `FileHint.min_size` / `FileHint.max_size` no longer
+  have a server-side second check during invocation. The browser applies them to
+  a file it has just picked, because there it holds the bytes and knows
+  `file.size`; a stored reference carries no bytes, the browser cannot weigh it
+  and the core no longer stats it. Do not expect a `422` from `/invoke` for byte
+  bounds on a reference. An application that needs an authoritative guarantee
+  about stored content owns that policy itself — FuncToWeb does not invent one
+  silently, and `max_upload_bytes` remains the endpoint policy it always was.
+- A file default written by the author as a server path is still refused unless
+  it belongs to the storage directory, and is still published as a reference and
+  never as a path. What changed is only what backs it: in 2.5.0 the core also
+  refused a default that did not exist, so a stale default failed at build time.
+  In 2.6.0 that default becomes a reference, and the resolver refuses it at
+  invocation instead, when it fails to resolve.
+
+### Fixed
+- `OpenForm` now forwards a union-valued prefill in the same transport a browser
+  submit sends, so an opening whose target has a parameter of two or more union
+  branches works. It answered `400` before, in every version that had the
+  feature: the opening published the plan's own way of writing a default —
+  `{"branch": …, "value": …}`, which names the control the page opens on — and
+  the destination reads a prefill as a submit, where a branch is named by the
+  value itself or not at all. Depending on the union the answer was
+  `expected int | str, got dict` or `ambiguous value: wrap it as $type`. The
+  conversion is the plan's own answer rather than a rule restated in FuncToWeb:
+  each branch already carries the mode `pytypehintweb` chose for it, and the
+  three modes emit what `form.js` emits — bare for `plain`,
+  `{"$type": …, "$value": …}` for `wrapped`, `{"$type": …, …fields}` for
+  `inline`. `X | None` was never affected and is unchanged: one real branch
+  compiles no choice at all, so the two spellings already agreed.
+
+### Unchanged, and now the only thing that says so
+- Reference syntax, separators, `..`, control characters, reserved names and
+  markers, and length limits stay in `segment_of()` / `stored_of()`.
+- Confinement to the uploads directory, in both directions: `stored_of()`
+  requires the resolved parent to be the storage root, and `reference_of()`
+  refuses a path whose round trip through storage does not land back on itself,
+  which is what keeps a symbolic link from escaping.
+- **Existence.** `stored_file()` promotes a pending upload or raises
+  `FileNotFoundError`, so a reference that does not resolve never reaches the
+  function. `/invoke` answers `422`; `/invoke-stream` answers `200` and carries
+  the same error in its `result` event, as it does for every rejection once the
+  stream is open. Either way the call is not made, and that refusal is a
+  FuncToWeb storage rule — after 2.6.0, the only one on this path.
+- `max_upload_bytes` is authoritative and unchanged: it may reject early on
+  `Content-Length`, but it never trusts it alone — the bytes are counted as they
+  arrive, the transfer is cut the moment the limit is passed, the partial file is
+  deleted and the answer is `413`.
+- The pending/promoted lifecycle, the sweeper, expiry and the reuse of a promoted
+  reference without a second upload.
+- `OpenForm` still hands a file on to the next function as a reference, hidden
+  and not re-uploaded; the local path never travels.
+
+### Dependencies
+- `pytypehintweb==0.0.5` → `pytypehintweb==1.1.0`, which brings `pytypehint
+  1.0.0` transitively. FuncToWeb still declares no direct dependency on
+  `pytypehint`: it arrives through `pytypehintweb`, as it has since 2.3.0.
+- 1.1.0 delegates the portable decoding to the core inside its own `decode()`:
+  it calls `schema.decode()` and then walks the decoded tree applying the
+  `file_resolver` to each file node. The simplification happens in
+  `pytypehintweb`; FuncToWeb implements none of it and its call sites are
+  unchanged.
+- The mypy exception `untyped_calls_exclude = ["pytypehintweb"]` is removed:
+  1.1.0 annotates `decode()`, so the package passes strict again with no
+  exemption.
+- `starlette==0.49.3` and `uvicorn==0.38.0` are unchanged.
+
 ## [2.5.0] - 2026-08-08
 
 FuncToWeb now depends directly on Starlette instead of FastAPI. `app_of()`
 
@@ -1,4 +1,4 @@
-# FuncToWeb 2.5.0
+# FuncToWeb 2.6.0
 
 [![PyPI version](https://img.shields.io/pypi/v/func-to-web.svg)](https://pypi.org/project/func-to-web/)
 [![Python](https://img.shields.io/pypi/pyversions/func-to-web.svg)](https://pypi.org/project/func-to-web/)
@@ -299,11 +299,11 @@ from typing import Annotated
 
 from PIL import Image
 
-from func_to_web import Download, IsPathFile, OpenForm, run
+from func_to_web import Download, FileHint, OpenForm, run
 
 ImagePath = Annotated[
     str,
-    IsPathFile(extensions=(".png", ".jpg", ".jpeg")),
+    FileHint(extensions=(".png", ".jpg", ".jpeg")),
 ]
 
 
@@ -354,9 +354,9 @@ itself, and that name has to exist when `choose_image` is defined.
 ```python
 from typing import Annotated
 
-from func_to_web import IsPathFile, Label, Min, run
+from func_to_web import FileHint, Label, Min, run
 
-AnyFile = Annotated[str, IsPathFile()]
+AnyFile = Annotated[str, FileHint()]
 
 Dropped = Annotated[list[AnyFile], Min(1), Label("Files to send")]
 
@@ -476,16 +476,16 @@ mini-app with the dict swapped for a store.
 
 Those three libraries are the whole stack: nested forms, recursive validation,
 streaming, the file lifecycle and the published contract are all inside these
-lines (v2.5.0, `.py`/`.js`/`.css` under `src/`).
+lines (v2.6.0, `.py`/`.js`/`.css` under `src/`).
 
 ```text
-pytypehint       1,987 lines    types, validation, defaults
-pytypehintweb    9,581 lines    plan, widgets, transport (includes the JS/CSS)
-FuncToWeb        5,070 lines    routes, execution, storage, /doc
-total           ~16,000 lines
+pytypehint       2,740 lines    types, validation, defaults
+pytypehintweb    9,468 lines    plan, widgets, transport (includes the JS/CSS)
+FuncToWeb        5,071 lines    routes, execution, storage, /doc
+total           ~17,300 lines
 ```
 
-Each layer can be read on its own: pytypehint is about 2,000 lines of pure
+Each layer can be read on its own: pytypehint is under 3,000 lines of pure
 stdlib and takes an afternoon, and no layer needs the others to be understood.
 The whole set also fits inside the context window of a general-purpose AI: you
 can hand over an entire library, or the three of them, and ask it to review,
@@ -521,7 +521,7 @@ practice.
 
 ## Status
 
-2.5.0 is a stable release: the public API is the one described in
+2.6.0 is a stable release: the public API is the one described in
 [`docs/`](docs/index.md), and the known limitations are listed in
 [limitations.md](docs/limitations.md).
 
 
@@ -52,8 +52,25 @@ it every other request the server is handling. See
 The `file_resolver` is the only piece of that path that belongs to FuncToWeb,
 and it is the same resolver in both endpoints and in the prefill: `decode()`
 decides **where** a file is, walking the structure to any depth, while
-FuncToWeb decides **what** counts as a valid file for this server. Neither
-layer duplicates the other's work.
+FuncToWeb decides **what** counts as a valid file for this server.
+
+That division is the whole story for a file, and no layer repeats another's
+work:
+
+```text
+browser         the extension and the size of the File the user just picked,
+                from the plan, before anything is uploaded
+POST /upload    the bytes on the wire, against max_upload_bytes
+file_resolver   the reference belongs to the storage directory, no traversal
+                and no symlink escape, the file is there → a local path
+pytypehint      the extension of that path, and the arguments themselves
+the function    receives the local path
+```
+
+Because nothing is checked twice, nothing can be dropped either — and the
+converse holds as well: what no layer checks is not checked at all. The byte
+bounds of a `FileHint` are the browser's alone; see
+[files.md](files.md#what-filehint-checks-and-where).
 
 ## Where it is mounted
 
 
@@ -1,76 +1,86 @@
 # Files: the upload endpoint, the reference and custody
 
 Why `/upload`, the reference and the pending cycle are built the way they are.
-The contract — what `IsPathFile` certifies, the rejection and limit tables, the
-pending/promoted cycle and the border between path and reference — is in
-[files.md](../files.md).
+The contract — what `FileHint` checks and which layer checks it, the rejection
+and limit tables, the pending/promoted cycle and the border between path and
+reference — is in [files.md](../files.md).
 
 ## The two messages of a file default
 
 The two [messages](../files.md#declaring-a-file-default) quote different things,
-because they happen at different moments. The first is the core reading the
-string as the author typed it, before anything has looked at the disk, so it
-echoes that string whole. The second is FuncToWeb turning an already certified
-path into the reference it will publish, and by then the directory is the part
-that must not travel, so only the name is left.
-
-## Why the endpoint does not apply the field limit
-
-The `IsPathFile` limits belong to the parameter, and `/upload` does **not**
-apply them. This is not an oversight:
+because two different layers say them. The first is the core reading the string
+as the author typed it, before anything has looked at the disk, so it echoes
+that string whole, directory included — the author is the one who wrote it, and
+it never leaves the process. The second is FuncToWeb turning that path into the
+reference it will publish, and by then the directory is the part that must not
+travel, so only the name is left.
+
+Neither of them touches the disk, and that is the honest shape of the check: the
+core compares an extension, FuncToWeb asks whether the name round-trips inside
+the storage directory. A default naming a file that is simply not there
+satisfies both. It is not a gap the build could close cheaply either — the path
+is read once, when the `WebFunction` is compiled, and a file that exists then
+can be gone by the time the first request arrives, so the answer that matters is
+the one the resolver gives on each execution.
+
+## Why `/upload` does not apply `FileHint.max_size`
+
+The `FileHint` limits belong to the parameter, and `/upload` does **not** apply
+them. The reason is *not* that something behind it will: nothing on the server
+weighs a stored file, so the endpoint is not standing aside for a verdict that
+comes later — no verdict comes.
 
 ```text
-max_upload_bytes          operational ceiling of the endpoint, cuts early
-IsPathFile.min/max_size   parameter constraint, validated on invocation
+max_upload_bytes         operational ceiling of the endpoint, counts the real
+                         bytes as they arrive
+FileHint.min/max_size    parameter constraint, applied by the browser to the
+                         File it is holding
 ```
 
-A request to `/upload` carries bytes and a reference. It does not say which
-parameter that reference will end up in, and it cannot: the same reference
-serves several executions, and inside a list, a union or a nested dataclass
-there is no reliable way to point at the node. Applying the field limit there
-would mean walking the schema a second time inside FuncToWeb, or trusting a size
-declared by the browser. Neither is acceptable.
-
-It is not needed, because the field limit is checked twice without FuncToWeb
-taking part:
-
-```text
-the browser   weighs the local File before uploading it   (pytypehintweb)
-the core      weighs the real file when building          (pytypehint)
-```
-
-The first saves the transfer; the second is the verdict, and it is the only one
-a hand-written HTTP call cannot skip.
-
-The browser's part is a courtesy, and it works with exactly what it can know: a
-freshly chosen `File` carries its `.size`, so it is weighed before anything is
-uploaded and, if it is over the limit, no reference is minted and nothing stays
-pending (a multiple selection with one bad file is rejected whole, not halfway).
-A reference supplied from outside names a file the browser never saw: there is
-no size to weigh, none is invented, and the server is not asked for one. A file
-edited after being uploaded, an expired reference or a hand-written client all
-end up in the same place: the core's measurement.
-
-So the split is:
+A request to `/upload` carries bytes and a reference, and nothing else. It does
+not say which parameter that reference will end up in, and it cannot: the same
+reference serves several executions, and it can feed two functions whose bounds
+disagree. Inside a list, a union or a nested dataclass there is no node to point
+at either. Applying the field limit there would mean walking the schema a second
+time inside FuncToWeb — a second validator alongside pytypehint's, with its own
+reading of the same atoms, drifting from it the first time the core changes.
+That is the one thing this layer has undertaken not to build.
+
+The two numbers are also different kinds of thing, and reading one as an
+implementation of the other is what produces the wrong expectation.
+`max_upload_bytes` is an operational policy of the endpoint: how much this
+server is willing to receive and keep, whatever it later turns out to be for.
+`FileHint.min_size`/`max_size` are part of the function's contract: what this
+parameter is prepared to work with. One belongs to the deployment, the other to
+the signature.
+
+So each layer applies what it can genuinely know. The browser holds a real
+`File` with a real `.size`, so it weighs it before anything is uploaded and, if
+it is outside the bounds, no reference is minted and nothing stays pending (a
+multiple selection with one bad file is rejected whole, not halfway). The
+endpoint holds bytes on the wire, so it counts them, stops mid-write, deletes
+the partial file and answers `413`. The core holds a string, so it reads its
+extension. Nobody stats the stored file.
 
 ```text
 upload too large for the server         → /upload responds 413
 local File that breaks the bound        → the form neither uploads nor sends it
-opaque reference that breaks the bound  → /upload accepts it,
-                                          /invoke responds 422
-file below the field's min_size         → /invoke responds 422
+opaque reference that breaks the bound  → /upload accepts it, /invoke runs
+reference that names nothing in storage → /invoke responds 422
 ```
 
-The `422` is not a failure of the function: it comes from `schema.build()`,
-after the resolver has turned the reference into a path, so the core measures
-the real file. It is input validation, with the core's message:
-
-```text
-{"error": "SchemaValueError: doc: file too small: 99 bytes, minimum 100"}
-```
+A reference supplied from outside names a file the browser never saw: there is
+no size to weigh, none is invented, and the server is not asked for one. A file
+edited after it was uploaded is in the same position, and so is a hand-written
+client. The size bound is simply not applied to any of them, and saying
+otherwise would be selling a guarantee this layer does not hold.
 
-The same holds inside a list, a dataclass or a union, because `decode()` does
-the walking and the core does the measuring.
+That is a deliberate boundary, not an open hole. An application that needs an
+authoritative rule about the size of stored content owns that rule: it can check
+it inside the function, which is the one place that has both the path and the
+contract in hand, or in whatever wraps the mount. FuncToWeb does not invent that
+policy on its behalf, and the one ceiling it does own, `max_upload_bytes`, it
+enforces on the bytes themselves, where no client can talk it out of the number.
 
 ## Why the name rules are portable
 
@@ -131,15 +141,36 @@ reference is what makes that decision genuinely yours —it never stops
 resolving and it never changes underneath you— so a retention policy written
 around it holds.
 
-## Why the resolver speaks first
-
-Both check that the file exists, and neither is redundant: the resolver decides
-whether the reference names something in the storage directory, and the core
-then certifies the path that came out of it. Since the resolver speaks first,
-the message you see on this path is the resolver's; the core's
-`file does not exist` is left for what does not go through the resolver, such as
-a default written in the signature, or for a file that disappears between one
-check and the other.
+## Why existence belongs to the resolver
+
+The resolver is not the first of two checks; it is the only one. It decides
+whether the reference names something this server owns: a bare file name, a
+resolved path whose immediate parent is `UPLOADS_DIR`, and a file actually
+sitting there —under the bare name, or as a pending one it promotes on the way.
+What comes out is a local path that still carries the extension the reference
+had, which is what makes `FileHint(extensions=…)` work end to end.
+
+The core repeats none of it. It does not stat, it does not test
+`Path.is_file()`, and a path that is not there builds without complaint, so
+there is no verdict waiting behind the resolver to catch what it let through.
+That is precisely why the rule is written once, on this side, and why the same
+resolver serves both execution endpoints and the prefill: the alternative here
+is not redundancy, it is a gap.
+
+It also explains the shape of the message. Every rejection on this path is the
+resolver's —`File not found: <reference>`, or the storage refusal— and it names
+the file by its reference, because that is the only name the client ever knew.
+
+The one value that skips the resolver is a default written in the signature,
+since there is nothing to resolve yet; it is checked for belonging to storage
+instead, which is what makes it publishable as a reference, and its existence is
+settled like everyone else's, on the first execution.
+
+The resolved path is local, and it keeps its extension because storage is a
+directory of files. A resolver that returned an opaque key with no extension
+(`s3://bucket/key` and the like) would break `FileHint` outright — the core has
+nothing but that string to read. FuncToWeb does not have such a resolver, and
+this is the assumption anyone writing one would have to keep.
 
 ## The author/client border