@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/shape.ts

@@ -0,0 +1,412 @@
+/**
+ * Helpers for rendering CMS values, safe to import from a client component.
+ *
+ * Deliberately free of `next/headers` and of any environment access — the fetcher in
+ * `./content` holds the API key and must stay server-side, and mixing the two is how a
+ * secret ends up in a browser bundle.
+ */
+
+export type MediaRef = null | {
+  alt?: null | string
+  filename?: null | string
+  /** Where the subject is, as percentages. Absent means dead centre. */
+  focalX?: null | number
+  focalY?: null | number
+  mimeType?: null | string
+  sizes?: Record<string, unknown> | null
+  /** Already absolute — the platform resolves it on the way out. */
+  url?: null | string
+}
+
+/** A page reference: an id at depth 0, a document once resolved. */
+export type PageRef = null | number | string | { slug?: null | string; title?: null | string }
+
+/** A button, as modelled by `link()` in `defineBlocks`. */
+export type LinkField = null | {
+  kind?: 'page' | 'url' | null
+  label?: null | string
+  newTab?: boolean | null
+  page?: PageRef
+  url?: null | string
+}
+
+/**
+ * A stored sentence: a link group with the line of copy that surrounds it.
+ *
+ * One more key than `LinkField` and otherwise identical, because that is what a sentence
+ * *is* — see `sentence()` in `defineBlocks.ts`. A site types its blocks with this wherever
+ * it declared one.
+ */
+export type SentenceField = null | (NonNullable<LinkField> & { text?: null | string })
+
+/** Attribute the dashboard looks for. Value is `${sectionIndex}.${fieldPath}`. */
+export const FIELD_ATTR = 'data-u90-field'
+
+/** Marks a page section so Canvas can outline the whole block when it is selected. */
+export const SECTION_ATTR = 'data-u90-section'
+
+/**
+ * Marks a field whose value is a rich text document rather than a run of words.
+ *
+ * The caret rules key off this. A rich field satisfies every other clause of "editable leaf" —
+ * no nested field markers, no media — so without it the frame would make a legal document
+ * contentEditable and the bridge would send back `innerText`, flattening every bullet and bold
+ * term on the first keystroke.
+ */
+export const RICH_ATTR = 'data-u90-rich'
+
+/** Mark a rich text field: editable, but through `u90:edit-rich`, never as plain words. */
+export const richField = (
+  base: number | undefined,
+  ...parts: (number | string)[]
+): Record<string, string> =>
+  base === undefined ? {} : { ...field(base, ...parts), [RICH_ATTR]: '' }
+
+/**
+ * Where to look for the thing a selection names, in the order the selection means it.
+ *
+ * Canvas selects containers as readily as leaves — a whole section, a list, a link's group —
+ * and only a leaf is ever annotated. `data-u90-field` exists on `7.benefits.0.line`; nothing
+ * carries `7.benefits`, and nothing carries `7`. So an exact-match-only lookup found the thing
+ * a client clicked exactly when they clicked a field, and nothing the rest of the time: picking
+ * a section in the rail outlined it correctly and left the page wherever it already was.
+ *
+ * Several questions, narrowest first, because they answer different things about the same string:
+ *
+ *  - **The element itself.** A leaf field, and the only case that was ever handled.
+ *  - **A collection row**, `@projects.42` — any field belonging to that row will do. A detail
+ *    page has no reason to render the `titleField` a deep link names: jdsi's project page marks
+ *    `heroTitle` and `overview` and never `name`, because the heading *is* the project. Exact
+ *    match therefore finds nothing on precisely the screen the link exists to open.
+ *  - **A layout block**, `~12.0` — the chrome around the page, addressed by layout id and the
+ *    entry's position in it. Any field of that entry will do, for the reason a row's will.
+ *  - **A section, by its own marker.** Preferred over the section's first field: the block is
+ *    what was selected and what gets outlined, so it is also what should be brought into view.
+ *  - **Anything inside it**, by dotted prefix. This is what carries a list and a group, and a
+ *    section whose site forgot its marker.
+ *
+ * Pure and separate from the DOM so the resolution order can be asserted directly — the
+ * scrolling it feeds cannot be.
+ */
+export const revealSelectors = (field: string): string[] => {
+  // Generated paths: letters, digits, dots, `@`. Escaping quotes is enough, and avoids
+  // depending on CSS.escape.
+  const quoted = field.replace(/"/g, '\\"')
+  const selectors = [`[${FIELD_ATTR}="${quoted}"]`]
+
+  if (field.startsWith('@')) {
+    const [collection, id] = field.slice(1).split('.')
+    /*
+     * Returns here rather than falling through to the dotted prefix below. A row's fields are
+     * already covered by the row prefix, and `@projects.42.name.` would ask for children of a
+     * leaf — a selector that can only ever match nothing.
+     */
+    if (collection && id) {
+      selectors.push(`[${FIELD_ATTR}^="${`@${collection}.${id}.`.replace(/"/g, '\\"')}"]`)
+    }
+    return selectors
+  }
+
+  if (field.startsWith('~')) {
+    const [layoutId, index] = field.slice(1).split('.')
+    /*
+     * No `SECTION_ATTR` selector, and that omission is why this branch exists rather than
+     * falling through to the one below. The `0` in `~12.0` is a position in the layout's own
+     * list of entries; a bare number *is* a page section index and nothing here is one. Asking
+     * for `data-u90-section="0"` would find an unrelated block of the page and scroll the
+     * client somewhere they did not ask to go — worse than not moving at all.
+     *
+     * Returns for the reason the `@` branch does: the block prefix already covers every field
+     * of the entry, and `~12.0.tagline.` would be children of a leaf.
+     */
+    if (layoutId && index) {
+      selectors.push(`[${FIELD_ATTR}^="${`~${layoutId}.${index}.`.replace(/"/g, '\\"')}"]`)
+    }
+    return selectors
+  }
+
+  if (/^\d+$/.test(field)) selectors.push(`[${SECTION_ATTR}="${quoted}"]`)
+
+  selectors.push(`[${FIELD_ATTR}^="${quoted}."]`)
+
+  return selectors
+}
+
+/**
+ * Whether the page is already showing this, so scrolling would only move it away.
+ *
+ * Two conditions, and the second is why this is a function rather than one comparison. "Fully
+ * on screen" is **unsatisfiable for anything taller than the viewport**, so applied to a
+ * section it answered "no" every time and re-centred a block the client was already reading —
+ * sometimes scrolling the part they were looking at off the top.
+ *
+ * So: a target that fits is settled when all of it is on screen, and a target that does not fit
+ * is settled when the screen is full of it. Neither needs a tolerance to be picked, which is
+ * the point — a fraction chosen here would be a number nobody could defend later.
+ */
+export const isSettledInView = (
+  rect: { bottom: number; height: number; top: number },
+  viewport: number,
+): boolean =>
+  rect.height > viewport
+    ? rect.top <= 0 && rect.bottom >= viewport
+    : rect.top >= 0 && rect.bottom <= viewport
+
+/**
+ * Mark an element as editable from the dashboard.
+ *
+ *   <h1 {...field(base, 'slides', i, 'title')}>{slide.title}</h1>
+ *
+ * Returns nothing when `base` is undefined — i.e. when the section isn't coming from
+ * the CMS — so a site with no CMS emits no editor attributes at all.
+ */
+export const field = (
+  base: number | undefined,
+  ...parts: (number | string)[]
+): Record<string, string> =>
+  base === undefined ? {} : { [FIELD_ATTR]: [base, ...parts].join('.') }
+
+/**
+ * Mark the outermost element of a page section.
+ *
+ *   <section {...section(fieldBase)}>…</section>
+ *
+ * `field` says which words a client is editing; this says which *block* those words are part
+ * of. Canvas needs both, because selecting a heading and selecting the block it sits in are
+ * two different selections that must both be able to draw the block's box: the outline around
+ * the whole section, and the block toolbar that stands at its top-left corner.
+ *
+ * **This existed as an attribute long before it existed as a helper, and nothing emitted it.**
+ * `SECTION_ATTR` was declared here, matched by the selection stylesheet in `bridge.tsx`, and
+ * used by `revealSelectors` to decide what to scroll into view — a complete feature with no
+ * way to be true. Selecting a section outlined nothing, because `[data-u90-section="0"]` has
+ * never matched an element on any site we ship. The rule was written for a mark no one had
+ * been given a way to write.
+ *
+ * One per block, on the block's own root — not on a wrapper the site's section loop adds. A
+ * wrapper is a box the design did not ask for, in a `<main>` that is usually a flex column;
+ * `display: contents` would avoid the box and take the outline with it, since an element that
+ * generates no box cannot be given one. The root is the only element that is reliably the
+ * section's own full extent.
+ *
+ * Undefined `base` returns nothing, exactly like `field`: a site rendering outside the CMS
+ * emits no editor attributes at all.
+ */
+export const section = (base: number | undefined): Record<string, string> =>
+  base === undefined ? {} : { [SECTION_ATTR]: String(base) }
+
+/**
+ * Mark a field belonging to a **collection row** rather than to a page section.
+ *
+ *   <span {...entryField('projects', project.id, 'name')}>{project.name}</span>
+ *
+ * The path is `@projects.42.name`: the `@` says "this lives in a collection, not in
+ * this page's sections", the slug names the record type and the id names the row.
+ *
+ * The id rather than the position, deliberately. A row's position is a property of
+ * how the client last sorted them and changes under the editor's feet; the id is what
+ * the row *is*, so an edit lands on the project the client clicked even if the list
+ * reorders between the click and the save.
+ *
+ * `undefined` id renders no marker at all, matching `field`'s behaviour for a section
+ * that isn't on the page — an unsaved row has nothing for an edit to address yet.
+ */
+export const entryField = (
+  collection: string,
+  id: number | string | undefined,
+  ...parts: (number | string)[]
+): Record<string, string> =>
+  id === undefined ? {} : { [FIELD_ATTR]: [`@${collection}`, id, ...parts].join('.') }
+
+/**
+ * Mark a field belonging to the **layout** the page is wrapped in — its header, its footer.
+ *
+ *   <p {...layoutField(layoutId, index, 'tagline')}>{text(entry.tagline, 'Since 1994')}</p>
+ *
+ * The path is `~12.0.tagline`: the `~` says "this lives in the chrome around the page, not in
+ * the page", the number after it names the layout document and the one after that is the
+ * entry's position in that layout's list of blocks.
+ *
+ * The id is carried for the reason `entryField` carries its collection: two frames open side
+ * by side can be on pages using different layouts, and "entry 0" is a different block in each,
+ * so an index alone cannot say which document an edit belongs to.
+ *
+ * The position rather than an id of its own, though, because a layout's entries are a list on
+ * the layout row and nothing in an entry is stable enough to name. Reordering the chrome does
+ * move what these addresses point at — which is right: the client dragged the block, and the
+ * block they dragged is the one they meant.
+ *
+ * `undefined` id renders no marker at all, matching `field` and `entryField` — a site being
+ * rendered with no layout behind it has nothing for an edit to address.
+ */
+export const layoutField = (
+  layoutId: number | string | undefined,
+  index: number,
+  ...parts: (number | string)[]
+): Record<string, string> =>
+  layoutId === undefined ? {} : { [FIELD_ATTR]: [`~${layoutId}`, index, ...parts].join('.') }
+
+/** Prefer a CMS string, fall back to what the site ships with. */
+export const text = (incoming: null | string | undefined, fallback: string): string => {
+  const trimmed = typeof incoming === 'string' ? incoming.trim() : ''
+  return trimmed.length > 0 ? trimmed : fallback
+}
+
+/** URL of an uploaded override, or null to fall back to a committed asset. */
+export const mediaUrl = (media: MediaRef): null | string => media?.url ?? null
+
+/**
+ * Where to anchor an image that its container crops — a CSS `object-position`.
+ *
+ * The client picks a point on the photograph in the dashboard; this is how that point survives
+ * into a site. It matters most exactly where a site looks best: a full-bleed hero at
+ * `object-cover` throws away whatever does not fit, and without this it always throws away the
+ * edges, however the picture is composed.
+ *
+ * `fallback` rather than a hard-coded `center`, because a site may already have tuned a
+ * position by hand for a committed image — jdsi's closing banner sits at `center 60%` — and an
+ * upload with no focal point set must not quietly undo that.
+ *
+ * Returns a string for `style={{ objectPosition }}` rather than a Tailwind class, because the
+ * values are arbitrary percentages and a class name cannot be built at runtime.
+ */
+export const mediaPosition = (media: MediaRef, fallback = 'center'): string => {
+  const x = media?.focalX
+  const y = media?.focalY
+  if (typeof x !== 'number' || typeof y !== 'number') return fallback
+  // Payload stores percentages. Clamped because a hand-edited row could hold anything.
+  const clamp = (value: number): number => Math.min(100, Math.max(0, value))
+  return `${clamp(x)}% ${clamp(y)}%`
+}
+
+/**
+ * Merge CMS entries over a list of committed defaults, by position.
+ *
+ * The defaults carry everything the CMS doesn't model — video files, poster variants,
+ * responsive hints — so assets stay put while the copy comes from the platform. Null
+ * and undefined are dropped so a blank CMS field can't erase a default, and assets
+ * cycle if the CMS has more entries than the build ships.
+ */
+export const mergeByIndex = <Default extends object, Incoming extends object>(
+  defaults: Default[],
+  incoming: Incoming[] | undefined,
+): (Default & Incoming)[] => {
+  if (!incoming?.length || defaults.length === 0) return defaults as (Default & Incoming)[]
+
+  return incoming.map((entry, index) => {
+    const fallback = defaults[index % defaults.length] as Default
+    const overrides = Object.fromEntries(
+      Object.entries(entry).filter(([, value]) => value !== null && value !== undefined),
+    ) as Incoming
+    return { ...fallback, ...overrides }
+  })
+}
+
+/** Href for a linked page: its slug, with `home` at the root. */
+const pageHref = (page: PageRef | undefined): null | string => {
+  if (!page || typeof page !== 'object') return null
+  const slug = typeof page.slug === 'string' ? page.slug.trim() : ''
+  if (slug.length === 0) return null
+  return slug === 'home' ? '/' : `/${slug}`
+}
+
+export type ResolvedLink = {
+  href: string
+  label: string
+  newTab: boolean
+}
+
+/**
+ * Turn a CMS link group into what a button needs.
+ *
+ * Each part falls back independently, because a client can set a label without touching
+ * the destination or the other way round. An untouched group arrives as an object of
+ * nulls, so the *presence* of the group is not evidence that anything was set — only a
+ * non-empty value is.
+ *
+ * A page link whose slug can't be resolved falls back to the committed href rather than
+ * to `/`: a link that quietly goes to the home page is worse than one that still goes
+ * where it used to.
+ */
+export const resolveLink = (
+  link: LinkField | undefined,
+  fallback: { href: string; label: string },
+): ResolvedLink => {
+  const url = typeof link?.url === 'string' ? link.url.trim() : ''
+  const chosen = link?.kind === 'url' ? (url.length > 0 ? url : null) : pageHref(link?.page)
+
+  return {
+    href: chosen ?? fallback.href,
+    label: text(link?.label, fallback.label),
+    newTab: link?.newTab === true,
+  }
+}
+
+/** The marker in a sentence's copy that says where its link falls. */
+const SENTENCE_LINK = '{link}'
+
+export type ResolvedSentence = ResolvedLink & {
+  /** The words after the link. Empty when the link ends the sentence. */
+  after: string
+  /** The words before the link. Empty when the link opens the sentence. */
+  before: string
+}
+
+/**
+ * Turn a CMS sentence into the three pieces a component renders: words, link, words.
+ *
+ * **The one place `{link}` is parsed**, so no site reimplements the split. A component
+ * writes `{before}<a>{label}</a>{after}` and is done.
+ *
+ * `before` and `after` are deliberately **not** put through `text()`. That helper trims,
+ * which is right for a heading and is exactly what broke the shape this replaces: the space
+ * between the copy and the link belongs to neither half, and trimming either one closes it
+ * up — `See ourPrivacy Policyfor how we handle your details.` The whole line is trimmed
+ * once, at its ends, where trailing space is only ever noise; the interior is the client's.
+ *
+ * A sentence with no marker still renders its link, after the copy with a space in front of
+ * it. A client rewriting the line around the marker is the likely accident, and dropping the
+ * link on the floor would take a privacy or terms link off the page silently — worse than a
+ * link in a slightly awkward place, which is at least visible and fixable.
+ */
+export const resolveSentence = (
+  stored: SentenceField | undefined,
+  fallback: { href: string; label: string; text: string },
+): ResolvedSentence => {
+  const link = resolveLink(stored, fallback)
+  const copy = (
+    typeof stored?.text === 'string' && stored.text.trim().length > 0 ? stored.text : fallback.text
+  ).trim()
+
+  const at = copy.indexOf(SENTENCE_LINK)
+  if (at === -1) return { ...link, after: '', before: copy.length > 0 ? `${copy} ` : '' }
+
+  return {
+    ...link,
+    after: copy.slice(at + SENTENCE_LINK.length),
+    before: copy.slice(0, at),
+  }
+}
+
+export { imagePosition } from './image'
+export type {
+  ImageValue,
+  ImageReadValue,
+  ImageSeedValue,
+  ImageCrop,
+  ImageFocalPoint,
+  ImageReadVariant,
+  ImageVariant,
+  ImageAsset,
+  ImageRendition,
+} from './image'
+
+export { videoProps } from './media'
+export type {
+  VideoValue,
+  VideoReadValue,
+  VideoSeedValue,
+  FileValue,
+  FileReadValue,
+  FileSeedValue,
+} from './media'

package/src/legacy/uploads.ts

@@ -0,0 +1,233 @@
+import type { EditorBlock, EditorField } from './contract'
+
+/**
+ * Finding the uploads inside a page's sections.
+ *
+ * Content is opaque JSON, so an upload is a bare id with nothing marking it as one.
+ * Three things need to locate them: the platform hydrates them on the way out to a
+ * site, guards against deleting a file a page still uses, and forces them back to ids
+ * on write; the site resolves them for live editing.
+ *
+ * **This lives in the shared package so there is exactly one traversal.** Two walkers
+ * that disagreed about which values are media would mean ids collected but not
+ * replaced — images silently missing, with no error anywhere. That is the failure this
+ * placement exists to prevent, and it is why the platform imports this rather than
+ * keeping its own copy.
+ *
+ * Driven by the site's own schema rather than by field names. A convention (`media`,
+ * `video`, `image`, …) would be a guess about a schema nobody here owns: the first site
+ * to call a field `photo` would lose its images and nothing would report it.
+ */
+
+/** A position in the content tree that holds an upload. */
+export type UploadSlot = {
+  get: () => unknown
+  set: (value: unknown) => void
+}
+
+const isMediaUpload = (field: EditorField): boolean =>
+  field.type === 'upload' && (field.relationTo === undefined || field.relationTo === 'media')
+
+/** An id as stored: a bare number or string, never an object. */
+export const asMediaId = (value: unknown): null | number | string => {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.length > 0) return value
+  // Already resolved, or populated by Payload. Recover the id.
+  if (value && typeof value === 'object') {
+    const id = (value as { id?: unknown }).id
+    if (typeof id === 'number' || typeof id === 'string') return id
+  }
+  return null
+}
+
+/**
+ * The blocks a zone field may hold, from whichever form it used.
+ *
+ * **This is a deliberate second copy of `childBlocksFor`** in
+ * `src/dashboard/canvas/nestedBlocks.ts` on the platform side — that module is the single
+ * authority for every consumer that *can* reach it, and this file cannot: the package is
+ * vendored into each client's site and must never import from the platform's `src/`. There is
+ * a **third** copy too — `childrenOf`/`seedZone` in `packages/site-kit/src/defineBlocks.ts`,
+ * this package's own seeding path, which cannot import from this file either without pulling
+ * upload-collection code somewhere that has nothing to do with it. Three copies, not a pair:
+ * change any one and change the other two; each of the three doc comments names all three
+ * files, on purpose, so a fourth copy — or a count that has quietly gone stale — is a
+ * three-way disagreement to notice rather than a "the pair" nobody thought to recount.
+ * `verify:nested-blocks` checks all three agree, not only `nestedBlocks.ts` and this file.
+ *
+ * The rule: `field.blocks` (inline definitions) is returned as-is when present, otherwise each
+ * entry of `field.childBlocks` (slugs) is looked up in the site's declared blocks, **in the
+ * order the site listed its slugs**, skipping any that names nothing. Exactly one form is ever
+ * present. The site's order rather than the block list's, because `of: ['navItem',
+ * 'productTile']` is the site saying which choice comes first — nothing here reads the order,
+ * but the platform's picker does, and a copy that resolved differently would be a copy that
+ * disagreed.
+ */
+const childrenOf = (field: EditorField, allBlocks: EditorBlock[]): EditorBlock[] => {
+  if (field.blocks !== undefined) return field.blocks
+
+  const resolved: EditorBlock[] = []
+  for (const slug of field.childBlocks ?? []) {
+    const block = allBlocks.find((entry) => entry.slug === slug)
+    if (block !== undefined) resolved.push(block)
+  }
+  return resolved
+}
+
+const collectFrom = (
+  fields: EditorField[],
+  container: unknown,
+  slots: UploadSlot[],
+  allBlocks: EditorBlock[],
+): void => {
+  if (!container || typeof container !== 'object') return
+  const record = container as Record<string, unknown>
+
+  for (const field of fields) {
+    const value = record[field.name]
+
+    if (isMediaUpload(field)) {
+      /*
+       * A `hasMany` upload yields one slot per element rather than one for the array.
+       *
+       * Every caller of this treats a slot as holding a single id — `collectMediaIds`
+       * asks `asMediaId` for it, `normaliseUploadsIn` writes one back — and `asMediaId`
+       * reads an array as an object with no `id`, so a whole-array slot collected
+       * nothing and *normalised the gallery to null on the next save*. Per element, all
+       * three walkers keep working unchanged, and the list keeps its order because each
+       * slot writes back to the index it came from.
+       */
+      if (Array.isArray(value)) {
+        value.forEach((_item, index) => {
+          slots.push({
+            get: () => (record[field.name] as unknown[])[index],
+            set: (next) => {
+              ;(record[field.name] as unknown[])[index] = next
+            },
+          })
+        })
+        continue
+      }
+
+      slots.push({
+        get: () => record[field.name],
+        set: (next) => {
+          record[field.name] = next
+        },
+      })
+      continue
+    }
+
+    if (field.type === 'group') {
+      collectFrom(field.fields ?? [], value, slots, allBlocks)
+      continue
+    }
+
+    if (field.type === 'array' && Array.isArray(value)) {
+      for (const item of value) collectFrom(field.fields ?? [], item, slots, allBlocks)
+      continue
+    }
+
+    if (field.type === 'blocks' && Array.isArray(value)) {
+      // A nested blocks field either carries its own definitions, which may differ from the
+      // page's top-level set, or names them by slug — see `childrenOf`. Reading `field.blocks`
+      // alone left a slug zone's allow-list empty, so an upload on a nested child was invisible
+      // to every one of this walker's three callers: it was never hydrated on egress, never
+      // guarded against deletion, and never normalised back to an id on write.
+      const nested = new Map(childrenOf(field, allBlocks).map((block) => [block.slug, block]))
+      for (const entry of value) {
+        const slug = (entry as { blockType?: unknown } | null)?.blockType
+        const block = typeof slug === 'string' ? nested.get(slug) : undefined
+        if (block) collectFrom(block.fields, entry, slots, allBlocks)
+      }
+    }
+  }
+}
+
+/**
+ * Every upload position in a page's content.
+ *
+ * A section whose `blockType` isn't in the schema is skipped: nothing can be said about
+ * the shape of a block there is no definition for, and guessing is how images get lost.
+ */
+export const uploadSlots = (
+  content: unknown,
+  blocks: EditorBlock[],
+  /**
+   * The site's whole declared block list, when it differs from `blocks` — the same split
+   * `validateContent` makes on the platform side. They are the same list for a page; they come
+   * apart for a collection row, whose `blocks` is the one-block `__entry` wrapper while its
+   * zones still name the site's own blocks by slug.
+   */
+  allBlocks: EditorBlock[] = blocks,
+): UploadSlot[] => {
+  if (!Array.isArray(content)) return []
+
+  const bySlug = new Map(blocks.map((block) => [block.slug, block]))
+  const slots: UploadSlot[] = []
+
+  for (const section of content) {
+    const slug = (section as { blockType?: unknown } | null)?.blockType
+    const block = typeof slug === 'string' ? bySlug.get(slug) : undefined
+    if (block) collectFrom(block.fields, section, slots, allBlocks)
+  }
+
+  return slots
+}
+
+/** Distinct media ids referenced by a page's content. */
+export const collectMediaIds = (
+  content: unknown,
+  blocks: EditorBlock[],
+  /** See `uploadSlots`. */
+  allBlocks: EditorBlock[] = blocks,
+): (number | string)[] => {
+  const ids = new Set<number | string>()
+  for (const slot of uploadSlots(content, blocks, allBlocks)) {
+    const id = asMediaId(slot.get())
+    if (id !== null) ids.add(id)
+  }
+  return [...ids]
+}
+
+/**
+ * Replace ids with resolved values, in place.
+ *
+ * An id with no match becomes `null` rather than staying a bare number: a site reading
+ * `media.url` off a number gets `undefined` and renders nothing, with no indication
+ * why. `null` is what a site's own fallback already handles.
+ */
+export const resolveUploadsIn = (
+  content: unknown,
+  blocks: EditorBlock[],
+  byId: Map<string, unknown>,
+  /** See `uploadSlots`. */
+  allBlocks: EditorBlock[] = blocks,
+): void => {
+  for (const slot of uploadSlots(content, blocks, allBlocks)) {
+    const id = asMediaId(slot.get())
+    if (id === null) continue
+    slot.set(byId.get(String(id)) ?? null)
+  }
+}
+
+/**
+ * Force every upload position back to a bare id, in place.
+ *
+ * What makes a mistake elsewhere recoverable rather than destructive: whatever shape an
+ * upload arrives in on a write, storage only ever holds an id. An object stored where an
+ * id belongs loses the reference permanently on the next save.
+ */
+export const normaliseUploadsIn = (
+  content: unknown,
+  blocks: EditorBlock[],
+  /** See `uploadSlots`. */
+  allBlocks: EditorBlock[] = blocks,
+): void => {
+  for (const slot of uploadSlots(content, blocks, allBlocks)) {
+    const current = slot.get()
+    if (current === null || current === undefined) continue
+    // An unresolvable value is cleared: storing an object here is what corrupts it.
+    slot.set(asMediaId(current))
+  }
+}

package/src/legacy/verification.ts

@@ -0,0 +1,42 @@
+// Legacy is packed on its own, so this helper must remain inside the legacy package.
+export type VerifyVisitor = (
+  request: Request,
+) => Promise<{ ok: true } | { ok: false; retryable: boolean }>
+/** Bound custom adapters as well as network adapters. Proof stays in this server-only request. */
+export async function verifyWithDeadline(
+  verifyVisitor: VerifyVisitor,
+  url: string,
+  proof: string,
+  signal?: AbortSignal,
+): Promise<Awaited<ReturnType<VerifyVisitor>>> {
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted) abort()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      new Promise<never>((_resolve, reject) => {
+        const fail = () => reject(new Error('Verification unavailable.'))
+        controller.signal.addEventListener('abort', fail, { once: true })
+        if (controller.signal.aborted) fail()
+        timer = setTimeout(() => controller.abort(), 10000)
+      }),
+      Promise.resolve().then(() => {
+        controller.signal.throwIfAborted()
+        return verifyVisitor(
+          new Request(url, {
+            method: 'POST',
+            body: JSON.stringify({ proof }),
+            headers: { 'content-type': 'application/json' },
+            signal: controller.signal,
+          }),
+        )
+      }),
+    ])
+  } finally {
+    clearTimeout(timer)
+    controller.abort()
+    signal?.removeEventListener('abort', abort)
+  }
+}