stitchkit 0.113.3 → 0.114.1

package/llms/react-keyboard.txt

@@ -46,6 +46,8 @@ key hears it first — a widget's own `onKeyDown`, a text field, a popover that
 closes on Escape — and keeps it with `preventDefault()` or `stopPropagation()`.
 A layer only gets what nobody nearer wanted, so third-party components keep
 working unchanged.
+One kind of layer may ask for the opposite: a menu over a text field takes the
+arrows before the field does — see [A menu over a text field](#a-menu-over-a-text-field).
 
 ## Shortcuts and Escape
 
@@ -125,7 +127,7 @@ function ChatList({ chats, openId, open }) {
 | Option | Default | Meaning |
 |---|---|---|
 | `items`, `value`, `onChange` | — | the ids in order, the chosen one, and the report of a choice; the zone never holds the value |
-| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`) |
+| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`). `'focus'`: an arrow only moves focus and the items choose for themselves — see [below](#links-and-buttons-that-choose-for-themselves) |
 | `orientation` | `'vertical'` | which arrows move; the other axis enters and exits |
 | `role` | `'listbox'` | `'listbox'` of options or `'tablist'` of tabs, marked `aria-selected`; `'none'` keeps the items' own semantics (links, buttons) and marks the chosen one `aria-current` |
 | `loop` | `false` | wrap past the ends instead of calling `onBoundary` |
@@ -134,6 +136,8 @@ function ChatList({ chats, openId, open }) {
 | `onBoundary(side)` | — | a move past `'start'` or `'end'`: hand focus to the neighbouring zone |
 | `active` | `true` | whether arrows pressed outside every zone land here |
 | `label` | — | the zone's accessible name |
+| `outside` | `'focus'` | what the first arrow does when focus is in no zone: `'focus'` puts focus on the current item and nothing else; `'move'` moves from it and, in select mode, chooses the neighbour — see [below](#the-first-arrow-from-outside-a-zone) |
+| `ignore(event)` | — | a key that is the application's own right now — return `true` and the zone leaves it whole; see [dragging](#a-zone-inside-a-drag-and-drop-list) |
 | `onReveal(id)` | — | focus went to an item with no element yet — a row of a virtualized list outside the rendered range; scroll it in, and focus lands on it when it mounts |
 
 The callbacks return `false` to leave the key to the page, anything else takes
@@ -146,6 +150,256 @@ axis puts focus on the active zone's current item. To move between zones
 (sidebar → table), call `zone.focus(id?)` of the other zone from `onEnter` or
 `onBoundary`. `zone.element` is the zone's element, for a layer scoped to it.
 
+## Links and buttons that choose for themselves
+
+In `select` and `highlight` mode the zone reports a choice, and in `highlight` it takes
+Enter for it. A list of `<a>` and `<button>` elements has a choice built in: Enter
+clicks the focused one. Taking Enter would replace that with a handler you must
+write to click the element yourself.
+
+`mode: 'focus'` is for those lists — a menu, a toolbar, a row of tabs that are
+links. The arrows move focus; Enter, and Space on a button, stay with the focused
+element; the zone reports nothing, so there is no `onChange`. `value` is optional
+and only marks the page you are on (`aria-current` with `role: 'none'`).
+
+```tsx
+function Toolbar({ actions }) {
+  const zone = useNavZone({
+    items: actions.map((action) => action.id),
+    mode: 'focus',
+    role: 'none',
+    orientation: 'horizontal',
+    label: 'Formatting',
+  })
+  return (
+    <div {...zone.zoneProps}>
+      {actions.map((action) => (
+        <button key={action.id} type="button" onClick={action.run} {...zone.itemProps(action.id)}>
+          {action.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+In a focus zone Enter is never taken, even when `onEnter` is set: `onEnter` is
+the cross-axis key (→ in a vertical zone).
+
+## Props, refs and other libraries
+
+Spread the zone's props **last** on an element another library also configures, so
+the roving `tabIndex` is the one that counts. A prop without a value is absent, not
+`undefined`: `role` is there only for a listbox or a tablist, `aria-selected` only
+outside `role: 'none'`, `aria-label` only with a `label`. A `role="button"` the
+element carries from another library, or an `aria-label` you wrote before the
+spread, survives it.
+
+`ref` is the one prop two libraries both need. `mergeRefs` makes one callback of
+several refs; spread the zone's props, then replace `ref`:
+
+```tsx
+import { mergeRefs, useNavZone } from 'stitchkit/react/keyboard'
+
+function Row({ id, zone }) {
+  const sortable = useSortable({ id })
+  const own = zone.itemProps(id)
+  return (
+    <li
+      {...sortable.attributes}
+      {...sortable.listeners}
+      {...own}
+      ref={mergeRefs(own.ref, sortable.setNodeRef)}
+    >
+      {id}
+    </li>
+  )
+}
+```
+
+The same goes for `zone.zoneProps.ref` beside a scroll container's or a measuring
+hook's ref. `mergeRefs` returns a new function on every call and React re-attaches a
+callback ref whose identity changed; a component that renders often keeps the
+result in `useMemo`.
+
+`useNavZone` also returns a new object on every render. An effect that should run
+when a menu *opens* depends on that, not on `zone`; keep the latest zone in a ref.
+
+## A zone inside a drag-and-drop list
+
+A sortable list is a zone whose rows can also be lifted with the keyboard: Space
+lifts a row, the arrows move it, Space drops it. The arrows are then the drag's,
+not the zone's, and a zone that also moves focus on them makes the focus ring jump
+from row to row while the row moves.
+
+`ignore` hands the zone a question about every key it would act on. dnd-kit marks
+the lifted activator `aria-pressed="true"` for the length of the drag:
+
+```tsx
+const zone = useNavZone({
+  items: order,
+  mode: 'focus',
+  role: 'none',
+  ignore: (event) =>
+    event.target instanceof Element && event.target.closest('[aria-pressed="true"]') !== null,
+})
+```
+
+The zone leaves an ignored key entirely: it does not move, does not take the key and
+does not call `preventDefault`, whether the key came from inside the zone or from
+a page whose focus is in no zone. The test is the application's on purpose. A
+toggle button also carries `aria-pressed="true"`, and a toolbar of toggles must
+keep its arrows; only the application knows whether a pressed element is a drag.
+
+## A menu or a popover opened by the pointer
+
+A script's `focus()` shows the focus ring when the element that had focus before it
+was showing one — and when nothing had. A menu opened by a right click, with focus
+on `body`, would put a ring on its first item although nobody pressed a key. Decide
+at the moment of opening: in the handler that opens the menu, before anything moves
+focus, ask `openedByKeyboard()`.
+
+```tsx
+const byKeyboard = useRef(false)
+const container = useRef<HTMLDivElement>(null)
+
+function show() {
+  byKeyboard.current = openedByKeyboard() // before the menu takes focus
+  setOpen(true)
+}
+
+useLayoutEffect(() => {
+  if (!open) return
+  if (byKeyboard.current) zone.focus() // the first item, with its ring
+  else container.current?.focus() // the menu itself
+}, [open])
+```
+
+`openedByKeyboard()` is whether the element with focus right now matches
+`:focus-visible`; it is `false` on a server and in a browser without that selector.
+Give the container `outline: none`: it only holds focus, and a browser may count a
+focus that starts on `body` as keyboard focus. The first arrow with focus on the
+zone's own element lands on the current item, not one step beyond it, so the menu
+opened by a click is a normal menu from the first key.
+
+A focus manager that also puts initial focus on opening fights this for the first
+item. Floating UI's `FloatingFocusManager` documents `initialFocus={-1}` as "ignore
+the initial focus" and `initialFocus={refs.floating}` as focusing the container;
+either leaves the first item to the handler above. (This repository's browser probe
+covers the pattern with a plain element, not Floating UI.)
+
+## The first arrow from outside a zone
+
+With focus in no zone — right after a click on the page, or on the empty part of a
+screen — the first arrow on an active zone's axis puts focus on its current item.
+That is the safe answer: the person sees where they are before anything changes,
+and a zone whose arrows choose does not change the choice on a key that only
+announced the list.
+
+A list that has always answered the first arrow with a change (a chat list whose
+arrows open the next chat) can say so: `outside: 'move'` acts as if focus were
+already on the current item, so the arrow moves from it and, in `select` mode,
+calls `onChange` for the neighbour. It is opt-in and per zone; `ignore` is asked
+first in both.
+
+## A panel that keeps its keys around a zone
+
+`data-local-keys` marks an area whose keys belong to it rather than to the page:
+layers skip keys pressed inside it, so a section switch on ← and → leaves a
+dropdown panel alone. A zone inside such a panel still has its arrows. The zone is
+the part of the area that handles them, so only a field *inside the zone* — an
+input in one of its rows — keeps its keys from the zone; an area that contains the
+zone, or the zone's own element carrying the mark, does not. ← and → are not a
+vertical zone's keys, so they bubble on to the layers, which skip them in that
+panel: the zone moves, the section does not.
+
+## A menu over a text field
+
+A layer hears a key after everything closer to it, and a text field is as close as
+it gets: the field acts on an arrow or Enter first. A menu that hangs over the
+field — slash commands, quick replies — keeps focus in the field and needs those
+keys *before* it does, and the field's own Enter (send the message) must not also
+run.
+
+`phase: 'capture'` is for that, and for a `local` layer only (any other kind
+refuses it when it mounts): the layer is asked before the element that has focus,
+and a key it takes — `preventDefault` and `stopPropagation` — reaches nothing
+nearer.
+
+```tsx
+function CommandMenu({ open, items, pick }) {
+  const menu = useRef<HTMLDivElement>(null)
+  const [index, setIndex] = useState(0)
+  useKeyLayer({
+    kind: 'local',
+    phase: 'capture',
+    fields: 'include', // the key is pressed in the field
+    scope: menu, // heard only while the menu is on the page
+    active: open,
+    onKey: (event) => {
+      if (event.key === 'ArrowDown') setIndex((i) => Math.min(i + 1, items.length - 1))
+      else if (event.key === 'ArrowUp') setIndex((i) => Math.max(i - 1, 0))
+      else if (event.key === 'Enter') pick(items[index])
+      else return false // typing, Backspace, everything else stays the field's
+      return true
+    },
+  })
+  return open ? <div ref={menu} role="listbox">…</div> : null
+}
+```
+
+`fields: 'include'` is needed because the default skips keys pressed in a field;
+`scope` and `active` keep the layer from taking keys when there is no menu. An
+`overlay` above still stops it: a live overlay is a barrier for layers of either
+phase. In `createKeyboardTestBed`, `press` runs the capture phase first and
+stops there when a layer took the key (`event.propagationStopped`).
+
+## Moving from a stack of zones of your own
+
+A hand-written zone stack and `stitchkit/react/keyboard` name the same ideas
+differently:
+
+| Yours | Here |
+|---|---|
+| a flag that arrows choose at once (`instant`) | `mode: 'select'`; `'highlight'` when choosing is expensive |
+| wrapping (often the default) | `loop` — `false` by default; set it on the lists that wrapped |
+| the current section | `active` for which zone takes the first arrow, `scope` for which layer is live |
+| one shared "highlighted id" | each zone's own focused item; read `zone.current` |
+| an attribute that marks areas with their own keys | `data-local-keys` |
+| Escape closing the innermost thing | `useEscapeLayer` — one Escape closes one level |
+
+## Testing without a DOM
+
+`stitchkit/react/keyboard/testing` has no React and no DOM in it: a window that
+remembers its listener, elements with a parent, `inert` and visibility, and key
+events with `preventDefault`. A test adds the layers a screen declares, presses
+keys on elements and reads who heard what.
+
+```ts
+import { createKeyboardTestBed } from 'stitchkit/react/keyboard/testing'
+
+test('Escape closes the dialog and not the page behind it', () => {
+  const bed = createKeyboardTestBed()
+  const heard: string[] = []
+  const page = bed.element()
+  const dialog = bed.element()
+  bed.stack.add({ kind: 'route', scope: () => page, onKey: () => (heard.push('page'), true) })
+  bed.stack.add({ kind: 'overlay', scope: () => dialog, onKey: () => (heard.push('dialog'), true) })
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+  page.inert = true // the page behind a dialog
+  dialog.hidden = true
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+})
+```
+
+`createNavZone` is the zone without React: build it with the items' fake elements
+(`bed.element({ zone: true })` and its `child()` rows count `focus()` and scrolling),
+call `zone.keyDown(bed.key('ArrowDown', { target: row }), zoneElement)`. A real
+focus ring, scrolling and screen readers are a browser's: this is for the order of
+layers, `scope`/`inert` and the edges of a zone.
+
 ## What stays in the application
 
 The URL, the router, sections and which screen is open. A layer calls the
@@ -168,13 +422,19 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 |--------|------|---------|
 | `useKeyLayer` | hook | put a layer on the window's one key stack — asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
 | `useEscapeLayer` | hook | an `overlay`, `local` or `route` layer for Escape: one press closes one level |
-| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select or highlight mode, cross-axis enter/exit, boundaries |
+| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value |
 | `nextZoneIndex` | function | where a move lands in a list of a given length: an index, `'before-start'` or `'after-end'` |
 | `isKeyFieldTarget` | function | whether a key was pressed in a field or a `data-local-keys` area, the test layers use |
-| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields` |
+| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields`, `phase` — `'capture'` is for a `local` layer only: it hears a key before the element that has focus does, as a menu over a text field must, and a key it takes goes no further |
+| `KeyLayerPhase` | _type_ | `'bubble' \| 'capture'` |
 | `KeyLayerKind` | _type_ | `'overlay' \| 'local' \| 'route' \| 'zone' \| 'global'` |
 | `EscapeLayerOptions` | _type_ | `kind`, `onEscape`, `active`, `scope` |
-| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode`, `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `label`, `onReveal` |
+| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode` (`select` or `highlight`), `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `outside` (`'focus'` or `'move'`: what the first arrow does when focus is in no zone), `label`, `onReveal`, `ignore` |
+| `FocusZoneOptions` | _type_ | the options of a zone whose items choose for themselves: `mode: 'focus'`, no `onChange`, an optional `value`; the arrows move focus and Enter stays with the focused element |
+| `ZoneOptions` | _type_ | `NavZoneOptions` or `FocusZoneOptions` — what `useNavZone` takes |
+| `ZoneKeyEvent` | _type_ | the key an `ignore` callback is asked about: `key`, modifiers, `target`, `repeat`, `isComposing`, `defaultPrevented` |
+| `mergeRefs` | function | one ref callback for several refs — the zone's `ref` beside a drag handle's or your own; spread the zone's props, then set `ref: mergeRefs(props.ref, other)` |
+| `openedByKeyboard` | function | whether the element with focus right now shows a focus ring — call it in the handler that opens a menu, before focus moves, to decide whether the first item takes focus |
 | `NavZone` | _type_ | what `useNavZone` returns — `zoneProps`, `itemProps(id)`, `element`, `current`, `focus(id?)` |
 | `NavZoneProps` / `NavZoneItemProps` | _type_ | the props spread on the zone's element and on each item |
 | `NextZoneIndexInput` | _type_ | `length`, `index`, `move`, `loop` |

package/llms/react.txt

@@ -144,7 +144,7 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 | `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
 | `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
 | `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |
-| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and comparator |
+| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and one ordering: `compare` (the whole array is sorted again after a create or update) or `insertCompare` (only a row entering the list is placed; every other row stays, and an updated row keeps its place) |
 | `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
 | `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |

package/llms/server.3.txt

@@ -868,6 +868,37 @@ deleted payload without guessing. The same resolved detail key drives the
 `isFresh` echo guard. Shape checks also leave neighbouring detail caches alone
 when a list key is intentionally used as a partial query-key prefix.
 
+### When only a new row needs an order
+
+`compare` is the order the row itself determines: the array is sorted again after
+every create and update, so a rename that moves a row moves it in the cache too.
+Some lists are ordered by facts the row does not carry — the projects a person
+owns first, then the ones they administer, then the rest by name, where the role
+is not in the row for a platform administrator who belongs to none of them. No
+`compare` can reproduce that, and sorting every row with a wrong one scrambles
+the list the server ordered.
+
+`insertCompare` answers a smaller question: where does a row that is *entering*
+the list go?
+
+```ts
+list: {
+  key: ['projects'],
+  shape: 'array',
+  createAt: 'end',
+  updateMissing: 'insert',
+  insertCompare: (incoming, existing) => incoming.name.localeCompare(existing.name),
+}
+```
+
+A new row goes before the first row it sorts ahead of; a tie goes by `createAt`
+(`'start'`: before equal rows, `'end'`: after them). On a list already in that
+order the result is the one `compare` would give. On a list that is not, no other
+row moves, and a row that is already in the list is replaced where it stands.
+A paged list places the row within the page `createAt` selects, and leaves the
+other pages as they were. `compare` and `insertCompare` are two answers to one
+question: a list takes one of them, and `createEntityCacheHandlers` refuses both.
+
 The helper deliberately does **not** flatten pages, infer filter semantics,
 derive a sort order or replace arbitrary `setQueryData` logic. Those remain
 declared application policies; Stitchkit applies their generic cache mechanics.

package/llms/server.4.txt

@@ -391,6 +391,11 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+`bot-to-bot-disabled` is permanent but deliberately not `recipientUnreachable`:
+Telegram returns it when either bot has not enabled Bot to Bot messaging, so the
+missing setting may be the sender's. Do not retry it, and do not close the
+recipient's row on it.
+
 `TELEGRAM_SEND_FAILURE_REASONS` lists every reason. A table keyed by
 `TelegramSendFailureReason` — error codes, the text a person reads — fails to
 compile when a release adds one, instead of falling through to a default:

package/llms/stitchkit.2.txt

@@ -16,6 +16,124 @@ Also read:
 # Guide: Typed client  (docs/guide/client.md)  (continued)
 ==============================================================================
 
+## Chunked uploads
+
+A file larger than one request goes as three calls of the application's own
+contract — open, parts, finish — driven by `uploadInChunks` on the client and
+held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
+the application's: its fields, its limits, what happens to the finished file.
+
+```ts
+// shared: one part size for both halves
+export const CHUNK_BYTES = 4 * 1024 * 1024
+
+// contract
+init: {
+  method: 'POST', path: '/uploads', desc: 'Open an upload',
+  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
+  output: z.object({ finished: Accepted.optional() }),
+},
+chunk: {
+  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
+  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
+  multipart: { files: { bytes: {} } },
+  output: z.object({ state: z.enum(['stored', 'repeated']) }),
+},
+finalize: {
+  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
+  params: z.object({ uploadId: z.string() }),
+  output: Accepted,
+},
+```
+
+```ts
+// server
+import { createChunkSpool } from 'stitchkit/files'
+
+const spool = createChunkSpool({
+  directory: env.UPLOAD_SPOOL_DIR,
+  chunkBytes: CHUNK_BYTES,
+  maxFileBytes: 1024 * 1024 * 1024,
+  meta: z.object({ name: z.string() }),
+})
+
+implement(contract, {
+  init: async ({ input, ctx }) => {
+    const done = await findFinished(input.uploadId) // the app's own record
+    if (done) return { finished: done }
+    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
+    return {}
+  },
+  chunk: async ({ params, files, ctx }) => ({
+    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
+  }),
+  finalize: async ({ params, ctx }) => {
+    const key = { owner: ctx.user.id, uploadId: params.uploadId }
+    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
+    const accepted = await store(file)
+    await spool.discard(key)
+    return accepted
+  },
+})
+```
+
+```ts
+// client — Bun, Node, a browser or React Native
+import { uploadInChunks } from 'stitchkit'
+
+const accepted = await uploadInChunks({
+  file,
+  chunkBytes: CHUNK_BYTES,
+  signal,
+  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
+  init: async (start, options) => {
+    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
+    return opened.finished ? { finished: opened.finished } : undefined
+  },
+  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
+  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
+})
+```
+
+The rules the two halves share:
+
+- **The client mints the upload id** (default `crypto.randomUUID()`, fresh per
+  call), so a repeated `init` is the same upload. The spool keys it by `owner`
+  too — the same id from another owner is another upload. To resume after the
+  app restarts instead of sending the file again, pass a stable `uploadId` —
+  the id of the app's own job or attempt.
+- **The file is anything with `size` and `slice(start, end)`** (`ChunkSource`).
+  A `Blob` is one; so is a platform file that is not a DOM `Blob`, such as an
+  Expo `File`, passed without a cast. A part's `bytes` is what `slice`
+  returns, so the part call hands it to the client as the multipart file.
+- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
+  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
+  (409). So the driver repeats `init` and a part on a failure that may pass — no
+  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
+  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
+- **`finalize` is never repeated.** After it the application owns the file and
+  the parts are gone; a lost answer is recovered by `init` returning
+  `{ finished }`, which the driver hands back without sending a byte.
+- **Cancellation is checked between parts**, so a cancelled upload never
+  reaches `finalize`.
+- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
+  up; the spool refuses anything else with a 4xx `AppError`
+  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
+  typed error. An application that maps error codes onto its own must map
+  these too — `isChunkSpoolErrorCode` / `CHUNK_SPOOL_ERROR_CODES` from
+  `stitchkit/files` — or a refusal reaches its client as an unknown 500.
+- **Progress counts file bytes**, inside a part too — the driver passes
+  `onUploadProgress` into the part call, so the [upload
+  progress](#upload-progress) route of the client applies. A repeated part
+  counts again from its start.
+- The first writer of a part wins across processes: its data file is named by
+  its hash and its receipt is published by an exclusive link. `sweep()` removes
+  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
+
+Part size is a latency decision: every part costs a round trip, so on a
+200 ms link a smaller part buys smoother progress at the price of a slower
+upload.
+
 ## Contract URL builders
 
 Browser-native consumers such as `<img src>`, downloads and navigation need a