@embedpdf/engine-core 3.0.0-next.0

package/dist/wire.js

@@ -0,0 +1,1280 @@
+import { n as checkCapability, t as checkAnyCapability } from "./resolver-DiPMTfcy.js";
+import { $ as PageStateSchema, $n as FreeTextIntentSchema, $t as SquigglyDraftSchema, A as FormSetValueResultSchema, An as FileAttachmentPatchSchema, At as AnnotationDTOSchema, B as PageDeleteResultSchema, Bn as CaretDraftSchema, Bt as UnderlinePatchSchema, C as FormEffectSchema, Cn as HighlightDraftSchema, Cr as PdfRotationSchema, Ct as FormKindSchema, D as FormFieldUpdateResultSchema, Dn as FreeTextPatchSchema, Dt as ToggleFieldWidgetSchema, E as FormFieldDeleteResultSchema, En as FreeTextDraftSchema, Et as FormWidgetRefSchema, F as MetadataUpdateResultSchema, Fn as EmbeddedFileRefSchema, Ft as UnsupportedDTOSchema, G as PageListSnapshotSchema, Gn as AnnotationFlagsPartialSchema, Gt as StrikeoutDTOSchema, H as PageFlattenResultSchema, Hn as AnnotationBaseShape, Ht as TextDTOSchema, I as MutationMetaSchema, In as CircleDTOSchema, It as UnsupportedDraftSchema, J as PageNetworkRenderFormatSchema, Jn as AnnotationRefSchema, Jt as ResourceRefSchema, K as PageMoveInputSchema, Kn as AnnotationFlagsSchema, Kt as StrikeoutDraftSchema, L as OpenDocumentResponseSchema, Ln as CircleDraftSchema, Lt as UnsupportedPatchSchema, M as LayerScopesSchema, Mn as WireAttachmentFileSchema, Mt as AnnotationPatchSchema, N as ManifestPageSchema, Nn as AttachmentFileInfoSchema, Nt as KIND_BY_SUBTYPE, O as FormImportResultSchema, On as FileAttachmentDTOSchema, Ot as WidgetPlacementSchema, P as MetadataPatchSchema, Pn as EmbeddedFileItemSchema, Pt as WidgetAppearanceSchema, Q as PageRotateResultSchema, Qn as ColorSchema, Qt as SquigglyDTOSchema, R as PageBoxesSchema, Rn as CirclePatchSchema, Rt as UnderlineDTOSchema, S as EngineErrorPayloadSchema, Sn as HighlightDTOSchema, Sr as PdfRectSchema, St as FormFieldValueSchema, T as FormFieldCreateResultSchema, Tn as FreeTextDTOSchema, Tt as FormValueEntrySchema, U as PageGeometrySnapshotSchema, Un as AnnotationBorderStyleSchema, Ut as TextDraftSchema, V as PageFlattenInputSchema, Vn as CaretPatchSchema, Vt as NoteIconSchema, W as PageLayoutSchema, Wn as AnnotationDraftBaseShape, Wt as TextPatchSchema, X as PageRenderQuerySchema, Xn as BlendModeSchema, Xt as StampWireDraftSchema, Y as PageRenderAnnotatedQuerySchema, Yn as AnnotationStableIdSchema, Yt as StampDTOSchema, Z as PageRotateInputSchema, Zn as CaretIntentSchema, Zt as StampWirePatchSchema, _ as CachePinsSchema, _n as LineDraftSchema, _r as CalloutLineSchema, _t as FormFieldFlagsSchema, a as AnnotationCreateResultSchema, an as PolylineDraftSchema, ar as RectSchema, at as RefetchReasonSchema, b as DocumentMetadataSchema, bn as InkDraftSchema, br as PdfPointSchema, bt as FormFieldPatchSchema, c as AnnotationListPageSnapshotSchema, cn as PolygonDraftSchema, cr as StrikeoutIntentSchema, ct as SearchQuerySchema, d as AnnotationUpdateResultSchema, dn as LinkDraftSchema, dr as PdfActionNodeSchema, dt as SearchSnippetSchema, en as SquigglyPatchSchema, er as InkIntentSchema, et as PageStructureCacheSchema, f as AppearanceOutcomeSchema, fn as LinkPatchSchema, fr as PdfActionTreeSchema, ft as WeakAnnotationSessionPagesRequestSchema, g as CacheDeltaSchema, gn as LineDTOSchema, gr as PdfPageActionsSchema, gt as FormFieldDraftSchema, h as AttachmentsCacheSchema, hn as PdfLinkTargetWritableSchema, hr as PdfFieldActionsSchema, ht as FormFieldDTOSchema, i as AnnotationAppearancesQuerySchema, in as PolylineDTOSchema, ir as PointSchema, it as RedactionApplyScopeSchema, j as FormWidgetLinkResultSchema, jn as FileAttachmentWireDraftSchema, jt as AnnotationDraftSchema, k as FormRepairResultSchema, kn as FileAttachmentIconSchema, kt as ANNOTATION_KINDS, l as AnnotationListSnapshotAllPagesSchema, ln as PolygonPatchSchema, lr as TextAlignmentSchema, lt as SearchRequestSchema, m as AttachmentDeleteResultSchema, mn as PdfLinkTargetSchema, mr as PdfAnnotationActionsSchema, mt as FormDataFormatSchema, n as AccessResponseSchema, nn as SquareDraftSchema, nr as LineEndingsSchema, nt as PdfSaveModeSchema, o as AnnotationDeleteResultSchema, on as PolylinePatchSchema, or as RevisionTokenSchema, ot as SearchMatchSchema, p as AttachmentCreateResultSchema, pn as PdfDestinationSchema, pr as PdfActionTypeSchema, pt as WeakAnnotationSessionResponseSchema, q as PageMoveResultSchema, qn as AnnotationPatchBaseShape, qt as StrikeoutPatchSchema, r as AnnotationAppearanceManifestSchema, rn as SquarePatchSchema, rr as PdfRectDifferencesSchema, rt as RedactionApplyResultSchema, s as AnnotationListMutationMetaSchema, sn as PolygonDTOSchema, sr as StandardFontSchema, st as SearchModeSchema, t as AccessRequestSchema, tn as SquareDTOSchema, tr as LineEndingSchema, tt as PageTextSnapshotSchema, u as AnnotationMoveResultSchema, un as LinkDTOSchema, ur as DocumentActionsSnapshotSchema, ut as SearchSliceSchema, v as DocumentHeadSchema, vn as LinePatchSchema, vr as InkListSchema, vt as FormFieldOptionInputSchema, w as FormEffectsResultSchema, wn as HighlightPatchSchema, wr as PdfSizeSchema, wt as FormSnapshotSchema, x as DocumentSecurityStateSchema, xn as InkPatchSchema, xr as PdfQuadSchema, xt as FormFieldRefSchema, y as DocumentManifestSchema, yn as InkDTOSchema, yr as LinePointsSchema, yt as FormFieldOptionSchema, z as PageDeleteInputSchema, zn as CaretDTOSchema, zt as UnderlineDraftSchema } from "./schemas-9OpSSeM6.js";
+//#region src/wire/token.ts
+const DEFAULT_MAX_TOKEN_LENGTH = 256;
+const FIELD_NAME_RE = /^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/;
+const VALUE_RE = /^[A-Za-z0-9.-]+$/;
+function encodeToken(schema, input) {
+	assertSchema(schema);
+	const allowed = new Set(schema.fields);
+	const pairs = [];
+	for (const [key, value] of Object.entries(input)) {
+		if (value === void 0) continue;
+		assertKnownField(allowed, key);
+		const encoded = encodeScalar(key, value);
+		assertSafeValue(key, encoded);
+		pairs.push([key, encoded]);
+	}
+	pairs.sort(([a], [b]) => a.localeCompare(b));
+	const token = pairs.map(([key, value]) => `${key}=${value}`).join(",");
+	if (token.length === 0) throw new Error("token must not be empty");
+	assertTokenLength(schema, token);
+	return token;
+}
+function decodeToken(schema, raw) {
+	assertSchema(schema);
+	const token = raw.startsWith("@") ? raw.slice(1) : raw;
+	assertTokenLength(schema, token);
+	if (token.length === 0) throw new Error("token must not be empty");
+	const allowed = new Set(schema.fields);
+	const output = {};
+	let previousKey;
+	for (const pair of token.split(",")) {
+		if (pair.length === 0) throw new Error("token contains an empty field");
+		const separator = pair.indexOf("=");
+		if (separator <= 0 || separator === pair.length - 1) throw new Error(`token field "${pair}" must be key=value`);
+		const key = pair.slice(0, separator);
+		const value = pair.slice(separator + 1);
+		assertKnownField(allowed, key);
+		assertSafeValue(key, value);
+		if (output[key] !== void 0) throw new Error(`token field "${key}" appears more than once`);
+		if (previousKey !== void 0 && key.localeCompare(previousKey) <= 0) throw new Error("token fields must be in alphabetical order");
+		previousKey = key;
+		output[key] = value;
+	}
+	return output;
+}
+function assertSchema(schema) {
+	for (const field of schema.fields) if (!FIELD_NAME_RE.test(field)) throw new Error(`token field name "${field}" must be camelCase segments joined by "."`);
+}
+function assertKnownField(allowed, key) {
+	if (!allowed.has(key)) throw new Error(`unknown token field "${key}"`);
+}
+function encodeScalar(key, value) {
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`token field "${key}" must be finite`);
+		return Number.isInteger(value) ? String(value) : trimDecimal(value);
+	}
+	return value;
+}
+function trimDecimal(value) {
+	return value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+function assertSafeValue(key, value) {
+	if (!VALUE_RE.test(value)) throw new Error(`token field "${key}" value contains a reserved character`);
+}
+function assertTokenLength(schema, token) {
+	const maxLength = schema.maxLength ?? DEFAULT_MAX_TOKEN_LENGTH;
+	if (token.length > maxLength) throw new Error(`token exceeds ${maxLength} characters`);
+}
+//#endregion
+//#region src/wire/tokenSchemas.ts
+const DocTokenSchema = { fields: ["docVersion"] };
+const ContentTokenSchema = { fields: ["contentVersion"] };
+const LayoutTokenSchema = { fields: ["layoutVersion"] };
+const MetadataTokenSchema = { fields: ["metadataVersion"] };
+const AnnotationTokenSchema = { fields: ["annotationVersion"] };
+const ActionsTokenSchema = { fields: ["actionsVersion"] };
+const AttachmentsTokenSchema = { fields: ["attachmentsVersion"] };
+const DownloadTokenSchema = {
+	fields: ["docVersion", "mode"],
+	maxLength: 128
+};
+/**
+* Allowed flat keys for the render token, expressed as dotted paths that
+* mirror the SDK `PageImageOptions` shape 1:1. The token codec is fully
+* generic over this list — adding a new render option means adding its
+* dotted path here and a matching branch in `PageImageOptionsWireSchema`.
+* No encoder/decoder code changes.
+*
+* `includeAnnotations` is deliberately NOT a token field: annotatedness
+* changes the artifact's plane-dependency
+* set, so it is expressed by the path FAMILY (`…/render/pages/` vs
+* `…/render/annotated/pages/`), never inside the token. `annotationVersion`
+* belongs to the annotated family's tokens only — each family's query
+* schema enforces its own pin grammar.
+*/
+const RenderTokenSchema = {
+	fields: [
+		"annotationVersion",
+		"background",
+		"contentVersion",
+		"format",
+		"quality",
+		"rotation",
+		"target.kind",
+		"target.rect.bottom",
+		"target.rect.left",
+		"target.rect.right",
+		"target.rect.top",
+		"viewport.kind",
+		"viewport.scale",
+		"viewport.width"
+	],
+	maxLength: 512
+};
+/**
+* Token for the versioned search endpoints (`/search/{rects,full}/data@…`).
+* One token carries the whole cache key: the content epoch, the query
+* (text/pattern rides base64-variant-encoded in `q` — the token value
+* charset excludes free text), and the resume position. Canonical by
+* construction: the codec sorts fields and the encoder omits every
+* default, so equal searches produce byte-equal tokens — the property CDN
+* cache hits live on. Mode is NOT a field; it is the endpoint (separate
+* permission tiers must never share cache entries).
+*/
+const SearchTokenSchema = {
+	fields: [
+		"epoch",
+		"matchCase",
+		"matchDiacritics",
+		"maxMatches",
+		"maxPages",
+		"q",
+		"regex",
+		"skip",
+		"startPage",
+		"wholeWord"
+	],
+	maxLength: 2048
+};
+/**
+* Token for the batch annotation-appearance render endpoint. Narrower than
+* the page render token: appearance bitmaps are sized per annotation `/Rect`
+* so there is no target/viewport — only a uniform `scale` and page
+* `rotation`. Keyed by `annotationVersion` only (appearances do not depend on
+* page base content). The cloud endpoint renders the Normal appearance only,
+* so `modes` is intentionally absent here (it is a worker/local-only option).
+*/
+const AnnotationAppearancesRenderTokenSchema = {
+	fields: [
+		"annotationVersion",
+		"format",
+		"quality",
+		"rotation",
+		"scale"
+	],
+	maxLength: 256
+};
+//#endregion
+//#region src/wire/tokens.ts
+const encodeDocToken = (docVersion) => encodeToken(DocTokenSchema, { docVersion });
+const decodeDocToken = (raw) => decodePositiveInteger(decodeToken(DocTokenSchema, raw).docVersion, "docVersion");
+const encodeContentToken = (contentVersion) => encodeToken(ContentTokenSchema, { contentVersion });
+const decodeContentToken = (raw) => decodePositiveInteger(decodeToken(ContentTokenSchema, raw).contentVersion, "contentVersion");
+const encodeLayoutToken = (layoutVersion) => encodeToken(LayoutTokenSchema, { layoutVersion });
+const decodeLayoutToken = (raw) => decodePositiveInteger(decodeToken(LayoutTokenSchema, raw).layoutVersion, "layoutVersion");
+const encodeMetadataToken = (metadataVersion) => encodeToken(MetadataTokenSchema, { metadataVersion });
+const decodeMetadataToken = (raw) => decodePositiveInteger(decodeToken(MetadataTokenSchema, raw).metadataVersion, "metadataVersion");
+const encodeAnnotationToken = (annotationVersion) => encodeToken(AnnotationTokenSchema, { annotationVersion });
+const decodeAnnotationToken = (raw) => decodePositiveInteger(decodeToken(AnnotationTokenSchema, raw).annotationVersion, "annotationVersion");
+const encodeActionsToken = (actionsVersion) => encodeToken(ActionsTokenSchema, { actionsVersion });
+const decodeActionsToken = (raw) => decodePositiveInteger(decodeToken(ActionsTokenSchema, raw).actionsVersion, "actionsVersion");
+const encodeAttachmentsToken = (attachmentsVersion) => encodeToken(AttachmentsTokenSchema, { attachmentsVersion });
+const decodeAttachmentsToken = (raw) => decodePositiveInteger(decodeToken(AttachmentsTokenSchema, raw).attachmentsVersion, "attachmentsVersion");
+const encodeDownloadToken = (input) => encodeToken(DownloadTokenSchema, {
+	docVersion: input.docVersion,
+	mode: input.mode
+});
+const decodeDownloadToken = (raw) => {
+	const decoded = decodeToken(DownloadTokenSchema, raw);
+	return {
+		docVersion: decodePositiveInteger(decoded.docVersion, "docVersion"),
+		mode: decodePdfSaveMode(decoded.mode)
+	};
+};
+/**
+* Encode a render token from a flat wire-shape input. The input is the
+* output of `flatten(...)` over an SDK `PageImageOptions`-shaped object plus
+* cache versions. Semantic invariants (viewport-kind XOR fields, per-family
+* pin grammar — annotatedness itself is PATH-expressed, never a token key —
+* target rect coherence) live in the per-family render query schemas —
+* running them here would duplicate the spec.
+*/
+const encodeRenderToken = (input) => encodeToken(RenderTokenSchema, input);
+/**
+* Decode a render token to a flat `Record<string, string>` of allowed
+* fields. Use `unflatten(...)` + `PageImageOptionsWireSchema.parse(...)` to
+* recover the nested SDK shape with full coercion + validation.
+*/
+const decodeRenderToken = (raw) => decodeToken(RenderTokenSchema, raw);
+/**
+* Encode an annotation-appearance render token from a flat wire-shape input
+* (the `flatten(...)` of an `AnnotationAppearanceImageOptions`-shaped object
+* plus cache versions). Semantic validation lives in
+* `AnnotationAppearancesQuerySchema`.
+*/
+const encodeAnnotationAppearancesRenderToken = (input) => encodeToken(AnnotationAppearancesRenderTokenSchema, input);
+/** Decode an annotation-appearance render token to a flat field map. */
+const decodeAnnotationAppearancesRenderToken = (raw) => decodeToken(AnnotationAppearancesRenderTokenSchema, raw);
+const encodeSearchToken = (input) => {
+	const q = input.query;
+	return encodeToken(SearchTokenSchema, {
+		epoch: input.epoch,
+		q: encodeTokenText(q.text),
+		regex: q.regex ? true : void 0,
+		matchCase: q.matchCase ? true : void 0,
+		matchDiacritics: q.matchDiacritics ? true : void 0,
+		wholeWord: q.wholeWord ? true : void 0,
+		startPage: input.startPage,
+		skip: input.skip > 0 ? input.skip : void 0,
+		maxPages: input.budget?.maxPages,
+		maxMatches: input.budget?.maxMatches
+	});
+};
+const decodeSearchToken = (raw) => {
+	const t = decodeToken(SearchTokenSchema, raw);
+	if (t.epoch === void 0) throw new Error("search token is missing \"epoch\"");
+	if (t.q === void 0) throw new Error("search token is missing \"q\"");
+	const query = {
+		text: decodeTokenText(t.q),
+		...t.regex === "true" ? { regex: true } : {},
+		...t.matchCase === "true" ? { matchCase: true } : {},
+		...t.matchDiacritics === "true" ? { matchDiacritics: true } : {},
+		...t.wholeWord === "true" ? { wholeWord: true } : {}
+	};
+	const maxPages = t.maxPages === void 0 ? void 0 : decodePositiveInteger(t.maxPages, "maxPages");
+	const maxMatches = t.maxMatches === void 0 ? void 0 : decodePositiveInteger(t.maxMatches, "maxMatches");
+	return {
+		epoch: t.epoch,
+		query,
+		...t.startPage === void 0 ? {} : { startPage: decodePositiveInteger(t.startPage, "startPage") },
+		skip: t.skip === void 0 ? 0 : decodePositiveInteger(t.skip, "skip"),
+		...maxPages !== void 0 || maxMatches !== void 0 ? { budget: {
+			...maxPages !== void 0 ? { maxPages } : {},
+			...maxMatches !== void 0 ? { maxMatches } : {}
+		} } : {}
+	};
+};
+const TOKEN_TEXT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.";
+function encodeTokenText(text) {
+	const bytes = new TextEncoder().encode(text);
+	let out = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const b0 = bytes[i];
+		const b1 = bytes[i + 1];
+		const b2 = bytes[i + 2];
+		out += TOKEN_TEXT_ALPHABET[b0 >> 2];
+		out += TOKEN_TEXT_ALPHABET[(b0 & 3) << 4 | (b1 ?? 0) >> 4];
+		if (b1 === void 0) break;
+		out += TOKEN_TEXT_ALPHABET[(b1 & 15) << 2 | (b2 ?? 0) >> 6];
+		if (b2 === void 0) break;
+		out += TOKEN_TEXT_ALPHABET[b2 & 63];
+	}
+	return out;
+}
+function decodeTokenText(encoded) {
+	if (encoded.length % 4 === 1) throw new Error("malformed token text");
+	const bytes = [];
+	let buffer = 0;
+	let bits = 0;
+	for (const ch of encoded) {
+		const value = TOKEN_TEXT_ALPHABET.indexOf(ch);
+		if (value < 0) throw new Error("malformed token text");
+		buffer = buffer << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push(buffer >> bits & 255);
+		}
+	}
+	return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes));
+}
+function decodePositiveInteger(raw, field) {
+	if (raw === void 0 || !/^\d+$/.test(raw)) throw new Error(`token field "${field}" must be a positive integer`);
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value <= 0) throw new Error(`token field "${field}" must be a positive integer`);
+	return value;
+}
+function decodePdfSaveMode(raw) {
+	if (raw === "incremental" || raw === "rewrite") return raw;
+	throw new Error(`token field "mode" must be "incremental" or "rewrite"`);
+}
+//#endregion
+//#region src/wire/paths.ts
+/**
+* Single source of truth for cloud HTTP paths. Both @cloudpdf/engine and
+* @cloudpdf/server import these so they cannot drift.
+*
+* **URL layout convention (paths v2)**
+*
+* Each resource type lives at its own distinct path prefix. This
+* lets prefix-matching CDNs (Bunny, Cloud CDN, Azure FD) enforce
+* per-resource scope at the edge — a Bunny token signed at
+* `/v1/docs/{id}/render/pages/` can only authorize render bytes,
+* never text or annotations.
+*
+* Shape:
+*   /v1/docs/{id}                                       — doc root
+*   /v1/docs/{id}/manifest@{ver}                        — doc-level read
+*   /v1/docs/{id}/render/pages/{N}/data@{ver}                — render is its own prefix
+*   /v1/docs/{id}/text/pages/{N}/data@{ver}                  — text is its own prefix
+*   /v1/docs/{id}/geometry/pages/{N}/data@{ver}              — geometry is its own prefix
+*   /v1/docs/{id}/layers/{L}/manifest@{ver}
+*   /v1/docs/{id}/layers/{L}/metadata@{ver}
+*   /v1/docs/{id}/layers/{L}/render/pages/{N}/data@{ver}
+*   /v1/docs/{id}/layers/{L}/text/pages/{N}/data@{ver}
+*   /v1/docs/{id}/layers/{L}/geometry/pages/{N}/data@{ver}
+*   /v1/docs/{id}/layers/{L}/annotations/pages/{N}/items@{ver}    — collection (read)
+*   /v1/docs/{id}/layers/{L}/annotations/pages/{N}/items          — collection (create)
+*   /v1/docs/{id}/layers/{L}/annotations/pages/{N}/items/{key}    — member
+*   /v1/docs/{id}/layers/{L}/annotations/pages/{N}/items/move     — batch reorder
+*   /v1/docs/{id}/layers/{L}/pages/move                           — batch page reorder
+*   /v1/docs/{id}/layers/{L}/pages/rotate                         — batch absolute rotation
+*   /v1/docs/{id}/layers/{L}/pages/delete                         — batch page delete
+*   /v1/docs/{id}/layers/{L}/form                                 — reconciled snapshot (read)
+*   /v1/docs/{id}/layers/{L}/form/fields                          — field collection (create)
+*   /v1/docs/{id}/layers/{L}/form/fields/{key}                    — field member (read/patch/delete)
+*   /v1/docs/{id}/layers/{L}/form/fields/{key}/value              — value write (fill)
+*   /v1/docs/{id}/layers/{L}/form/fields/{key}/reset              — reset to /DV (fill)
+*   /v1/docs/{id}/layers/{L}/form/fields/{key}/widgets            — adopt a widget (attach)
+*   /v1/docs/{id}/layers/{L}/form/fields/{key}/widgets/detach     — release a widget
+*   /v1/docs/{id}/layers/{L}/form/data                            — FDF/XFDF export (GET) / import (POST)
+*   /v1/docs/{id}/layers/{L}/form/repair                          — durable reconciliation
+*   /v1/docs/{id}/layers/{L}/download@{ver}
+*
+* `items` appears on both the read collection (`items@{ver}`) and
+* the mutation surface (`items` POST, `items/{key}` PATCH/DELETE)
+* for symmetry — `items@version` is the page's versioned annotation
+* collection; `items/{key}` is one annotation inside it.
+*/
+const DEFAULT_LAYER_NAME = "default";
+const wirePaths = {
+	/** POST: grant document access/caching credentials for the current bearer. */
+	access: "/v1/access",
+	/**
+	* GET: open the document referenced by the doc-scoped JWT and
+	* return its `DocumentHead`. The server materialises the base
+	* PDF into its file cache and binds it to a worker the first
+	* time this is hit.
+	*/
+	docHead: (docId) => `/v1/docs/${encodeURIComponent(docId)}/head`,
+	/**
+	* GET: layer-scoped head. The cloud SDK always uses a layer namespace;
+	* tokens without `layer_name` bind to `DEFAULT_LAYER_NAME`.
+	*/
+	layerHead: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/head`,
+	/**
+	* GET: full document manifest at a specific `docVersion`. Content-
+	* addressed: the URL bytes are immutable for the lifetime of the
+	* version, so CDNs may cache `public, max-age=31536000, immutable`.
+	* A request whose `docVersion` mismatches the current version
+	* returns 404 — the SDK refetches `/head` to learn the new
+	* version, then re-requests the manifest at the new URL.
+	*/
+	docManifest: (docId, docVersion) => `/v1/docs/${encodeURIComponent(docId)}/manifest@${encodeDocToken(docVersion)}`,
+	/**
+	* GET: full layer manifest at a specific layer document version.
+	* Never-mutated layers may fall through to the immutable base view;
+	* once a layer row exists, `layers.doc_version` and `layer_pages`
+	* drive the response.
+	*/
+	layerManifest: (docId, layerName, docVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/manifest@${encodeDocToken(docVersion)}`,
+	/**
+	* GET: page-geometry list for the whole layer at a specific
+	* `layoutVersion`. Content-addressed; CDN may cache forever. The
+	* `layoutVersion` lives in the manifest (doc-level pointer) and bumps
+	* only on structural page ops. Stale-version requests 404 and the SDK's
+	* transparent retry walks `/head` -> `/manifest@docVersion=N` to learn
+	* the new `layoutVersion`.
+	*/
+	layerLayout: (docId, layerName, layoutVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/layout@${encodeLayoutToken(layoutVersion)}`,
+	/**
+	* Immutable BASE page-geometry list (plane-scope model): the shared-URL
+	* variant a layout-inheriting layer resolves at — every visitor's page
+	* list is ONE CDN object served from the base worker session.
+	*/
+	docLayout: (docId, layoutVersion) => `/v1/docs/${encodeURIComponent(docId)}/layout@${encodeLayoutToken(layoutVersion)}`,
+	layerLayoutCurrent: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/layout`,
+	/**
+	* GET: full document metadata for the layer at a specific
+	* `metadataVersion`. Content-addressed; CDN may cache forever. The
+	* `metadataVersion` lives in the manifest (doc-level pointer) and bumps
+	* only on metadata writes. Stale-version requests 404 and the SDK's
+	* transparent retry walks `/head` -> `/manifest@docVersion=N` to learn
+	* the new `metadataVersion`.
+	*/
+	layerMetadata: (docId, layerName, metadataVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/metadata@${encodeMetadataToken(metadataVersion)}`,
+	layerMetadataCurrent: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/metadata`,
+	/** Immutable BASE metadata (plane-scope model): the shared-URL variant a
+	*  metadata-inheriting layer resolves at. */
+	docMetadata: (docId, metadataVersion) => `/v1/docs/${encodeURIComponent(docId)}/metadata@${encodeMetadataToken(metadataVersion)}`,
+	/** Immutable catalog-owned actions, independently pinned in the manifest. */
+	layerActions: (docId, layerName, actionsVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/actions@${encodeActionsToken(actionsVersion)}`,
+	/** Immutable BASE catalog actions (plane-scope model): the shared-URL
+	*  variant an actions-inheriting layer resolves at. */
+	docActions: (docId, actionsVersion) => `/v1/docs/${encodeURIComponent(docId)}/actions@${encodeActionsToken(actionsVersion)}`,
+	/** POST: rewrite the document Info dict for the layer (metadata edit). */
+	layerMetadataUpdate: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/metadata`,
+	/**
+	* Immutable BASE /EmbeddedFiles listing: the shared-URL variant an
+	* attachments-undiverged layer resolves at — every visitor's sidebar list
+	* is ONE CDN object served from the base worker session.
+	*/
+	docAttachments: (docId, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/attachments@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/** Immutable BASE decoded bytes of one embedded file (twin of
+	*  `layerAttachmentFile` — same capability tier split). */
+	docAttachmentFile: (docId, key, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/attachment-files/${encodeTokenText(key)}/data@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/** Immutable /EmbeddedFiles listing, pinned by `attachmentsVersion`. */
+	layerAttachments: (docId, layerName, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/attachments@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/** POST: create a document-level embedded file (multipart mutation envelope). */
+	layerAttachmentsCollection: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/attachments`,
+	/** DELETE: remove a document-level embedded file by name-tree key. */
+	layerAttachmentItem: (docId, layerName, key) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/attachments/${encodeTokenText(key)}`,
+	/**
+	* Immutable decoded bytes of one document-level embedded file. Lives
+	* under its own `attachment-files` prefix — a stronger capability tier
+	* than the metadata listing, so a CDN credential for one can never
+	* authorize the other (the search-rects/search-full rule).
+	*/
+	layerAttachmentFile: (docId, layerName, key, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/attachment-files/${encodeTokenText(key)}/data@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/** Immutable decoded bytes of a FileAttachment annotation's embedded file. */
+	layerAnnotationFile: (docId, layerName, pageObjectNumber, annotKey, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/attachment-files/pages/${pageObjectNumber}/items/${encodeURIComponent(annotKey)}/data@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/**
+	* Immutable BASE bytes of a FileAttachment annotation's embedded file
+	* (plane-scope model). Depends on the `annotations` plane (the annotation
+	* exists in this view) AND the `attachments` plane (the pin); the origin
+	* guard requires both inherited.
+	*/
+	docAnnotationFile: (docId, pageObjectNumber, annotKey, attachmentsVersion) => `/v1/docs/${encodeURIComponent(docId)}/attachment-files/pages/${pageObjectNumber}/items/${encodeURIComponent(annotKey)}/data@${encodeAttachmentsToken(attachmentsVersion)}`,
+	/**
+	* GET: full plain-text extraction for a single page at a specific
+	* `contentVersion`. Content-addressed; CDN may cache forever.
+	* Stale-version requests return 404 and the SDK's transparent
+	* retry walks `/head` → `/manifest@docVersion=N` to learn the new
+	* `contentVersion`.
+	*/
+	docPageText: (docId, pageObjectNumber, contentVersion) => `/v1/docs/${encodeURIComponent(docId)}/text/pages/${pageObjectNumber}/data@${encodeContentToken(contentVersion)}`,
+	layerPageText: (docId, layerName, pageObjectNumber, contentVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/text/pages/${pageObjectNumber}/data@${encodeContentToken(contentVersion)}`,
+	layerPageTextCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/text/pages/${pageObjectNumber}/data`,
+	docPageGeometry: (docId, pageObjectNumber, contentVersion) => `/v1/docs/${encodeURIComponent(docId)}/geometry/pages/${pageObjectNumber}/data@${encodeContentToken(contentVersion)}`,
+	docPageGeometryCurrent: (docId, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/geometry/pages/${pageObjectNumber}/data`,
+	docPageRender: (docId, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/render/pages/${pageObjectNumber}/data@${encodeRenderToken(token)}`,
+	docPageRenderCurrent: (docId, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/render/pages/${pageObjectNumber}/data`,
+	/**
+	* Immutable BASE annotated render (plane-scope model). Its OWN path family,
+	* not a token flag under `/render/pages/`: an annotated render depends on
+	* `content + annotations`, an annotation-free one on `content` alone, and
+	* edge grants are prefix-scoped — the prefix law says a path's prefix must
+	* identify its full plane-dependency set. Annotatedness is therefore
+	* PATH-ONLY (the token/path law): the wire token has no
+	* `includeAnnotations` key at all; the annotated family's token carries
+	* `annotationVersion`, the free family's cannot.
+	*/
+	docPageRenderAnnotated: (docId, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/render/annotated/pages/${pageObjectNumber}/data@${encodeRenderToken(token)}`,
+	layerPageGeometry: (docId, layerName, pageObjectNumber, contentVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/geometry/pages/${pageObjectNumber}/data@${encodeContentToken(contentVersion)}`,
+	layerPageGeometryCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/geometry/pages/${pageObjectNumber}/data`,
+	layerPageRender: (docId, layerName, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/render/pages/${pageObjectNumber}/data@${encodeRenderToken(token)}`,
+	layerPageRenderCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/render/pages/${pageObjectNumber}/data`,
+	/** Layer twin of `docPageRenderAnnotated` — the grammar is uniform:
+	*  annotatedness is path-only at BOTH tiers. */
+	layerPageRenderAnnotated: (docId, layerName, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/render/annotated/pages/${pageObjectNumber}/data@${encodeRenderToken(token)}`,
+	layerPageRenderAnnotatedCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/render/annotated/pages/${pageObjectNumber}/data`,
+	/**
+	* Immutable BASE annotation list for a single page (plane-scope model):
+	* the shared-URL variant an annotations-inheriting layer resolves at — a
+	* base's own annotations (weak-identity ones included) are simply visible
+	* through every pristine layer, so 1,000 visitors' sidebars are ONE CDN
+	* object served from the base worker session.
+	*/
+	docPageAnnotations: (docId, pageObjectNumber, annotationVersion) => `/v1/docs/${encodeURIComponent(docId)}/annotations/pages/${pageObjectNumber}/items@${encodeAnnotationToken(annotationVersion)}`,
+	/** Immutable BASE appearance batch (twin of
+	*  `layerPageAnnotationAppearances` — same `annotations` plane gate). */
+	docPageAnnotationAppearances: (docId, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/annotations/pages/${pageObjectNumber}/appearances@${encodeAnnotationAppearancesRenderToken(token)}`,
+	/**
+	* GET: full annotation list for a single page at a specific
+	* `annotationVersion`. Same cache-control rules and 404-retry
+	* semantics as `docPageText`. The `items` suffix is the
+	* collection name — see file-level docstring.
+	*/
+	layerPageAnnotations: (docId, layerName, pageObjectNumber, annotationVersion) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/items@${encodeAnnotationToken(annotationVersion)}`,
+	layerPageAnnotationsCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/items`,
+	/**
+	* GET: batch-rendered annotation appearance bitmaps for a single page as a
+	* `multipart/form-data` body. Sibling collection of `items` under the same
+	* `annotations/pages/{N}/` resource, so it shares the `annotations-read`
+	* gate (`doc.annotate.read`) and CDN coverage — reading an annotation lets
+	* you see its rendered appearance, the same boundary Adobe uses.
+	*
+	* Content-addressed via the appearance render token (`annotationVersion`
+	* plus render options like scale/format); CDN may cache forever. Appearance
+	* pixels depend only on the annotation `/AP` stream, so `contentVersion` is
+	* deliberately NOT part of the key.
+	*/
+	layerPageAnnotationAppearances: (docId, layerName, pageObjectNumber, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/appearances@${encodeAnnotationAppearancesRenderToken(token)}`,
+	layerPageAnnotationAppearancesCurrent: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/appearances`,
+	layerPageAnnotationsCreate: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/items`,
+	layerAnnotationByKey: (docId, layerName, pageObjectNumber, key) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/items/${encodeURIComponent(key)}`,
+	layerPageAnnotationsMove: (docId, layerName, pageObjectNumber) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/annotations/pages/${pageObjectNumber}/items/move`,
+	/**
+	* GET: the reconciled form snapshot (field tree + widget joins) for the
+	* layer's CURRENT state. Forms are document-scoped (one AcroForm per
+	* document), so there is no per-page collection and — unlike annotations —
+	* no content-addressed `@version` variant: the snapshot is always served
+	* `no-store`. Mutation results carry the per-page `cacheDelta` that keeps
+	* annotation/render caches coherent when widget appearances change.
+	*/
+	layerForm: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form`,
+	/** POST: create a field (optionally with styled widget placements). */
+	layerFormFields: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields`,
+	/**
+	* Field member: GET (single field) / PATCH (updateField) / DELETE
+	* (deleteField + widget cascade). `fieldKey` is an encoded `FormFieldRef`
+	* (`encodeFieldRefKey`): `obj:12` or `fqn:billing.name`.
+	*/
+	layerFormFieldByKey: (docId, layerName, fieldKey) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields/${encodeURIComponent(fieldKey)}`,
+	/** POST: replace the field's value (`{ value: FormFieldValue }`). */
+	layerFormFieldValue: (docId, layerName, fieldKey) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields/${encodeURIComponent(fieldKey)}/value`,
+	/** POST: reset the field to /DV (or clear). Empty body. */
+	layerFormFieldReset: (docId, layerName, fieldKey) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields/${encodeURIComponent(fieldKey)}/reset`,
+	/** POST: adopt an inert widget annotation (`{ widget, onState? }`). */
+	layerFormFieldWidgets: (docId, layerName, fieldKey) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields/${encodeURIComponent(fieldKey)}/widgets`,
+	/**
+	* POST: release a widget back to the inert annotation plane
+	* (`{ widget }`). An action POST rather than a member DELETE because a
+	* widget ref is a (page, annotation) pair — carrying it in the body keeps
+	* one codec instead of inventing a second composite key syntax.
+	*/
+	layerFormFieldWidgetsDetach: (docId, layerName, fieldKey) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/fields/${encodeURIComponent(fieldKey)}/widgets/detach`,
+	/**
+	* GET: serialized form data (`?format=fdf|xfdf`, default `xfdf`).
+	* POST: import an FDF/XFDF payload (raw bytes body; format sniffed
+	* server-side unless `?format=` pins it).
+	*/
+	layerFormData: (docId, layerName, format) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/data${format ? `?format=${format}` : ""}`,
+	/** POST: durable reconciliation (`{ bakeAppearances? }`). */
+	layerFormRepair: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/repair`,
+	layerFormEffects: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/form/effects`,
+	/**
+	* GET: one budgeted search slice, versioned form. The token
+	* (`encodeSearchToken`) IS the cache key: content epoch + query +
+	* position. Immutable; CDN may cache forever. Mode is the path — rects
+	* and full are separate resources so permission tiers never share
+	* cache entries (`'rects'` needs `doc.text.search`; `'full'` also
+	* needs `doc.text.copy`).
+	*/
+	layerSearchRects: (docId, layerName, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/search/rects/data@${token}`,
+	layerSearchFull: (docId, layerName, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/search/full/data@${token}`,
+	/**
+	* GET: unversioned form — same fields as flat query params (`q` as
+	* plain text), served from the CURRENT content, always `no-store`.
+	* The debug/simple-client variant; the SDK uses the versioned form.
+	*/
+	layerSearchRectsCurrent: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/search/rects/data`,
+	layerSearchFullCurrent: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/search/full/data`,
+	layerPagesMove: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/pages/move`,
+	layerPagesRotate: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/pages/rotate`,
+	layerPagesDelete: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/pages/delete`,
+	layerPagesFlatten: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/pages/flatten`,
+	layerRedactionsApply: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/redactions/apply`,
+	layerEvents: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/events`,
+	layerDownload: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/download`,
+	layerDownloadVersioned: (docId, layerName, token) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/download@${encodeDownloadToken(token)}`,
+	/**
+	* Weak-annotation-sessions: pluralized in v2 so the collection
+	* lives at `/weak-annotation-sessions` and members at
+	* `/weak-annotation-sessions/{sessionId}` — REST-conventional.
+	*/
+	layerWeakAnnotationSession: (docId, layerName) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/weak-annotation-sessions`,
+	layerWeakAnnotationSessionHeartbeat: (docId, layerName, sessionId) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/weak-annotation-sessions/${encodeURIComponent(sessionId)}/heartbeat`,
+	layerWeakAnnotationSessionPages: (docId, layerName, sessionId) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/weak-annotation-sessions/${encodeURIComponent(sessionId)}/pages`,
+	layerWeakAnnotationSessionRelease: (docId, layerName, sessionId) => `/v1/docs/${encodeURIComponent(docId)}/layers/${encodeURIComponent(layerName)}/weak-annotation-sessions/${encodeURIComponent(sessionId)}`,
+	/**
+	* POST: pre-warm the doc cache + worker open before any user
+	* request lands. Body is `{ docId }`. Doc-scoped token required.
+	*/
+	docWarm: "/v1/warm"
+};
+//#endregion
+//#region src/wire/resources.ts
+/**
+* URL layout (paths v2): each resource type lives at a distinct path
+* prefix so prefix-matching CDNs (Bunny, Cloud CDN, Azure FD) can
+* enforce per-resource scope at the edge. See wire/paths.ts for the
+* full shape and rationale.
+*/
+const DOC_RESOURCES = {
+	head: {
+		id: "head",
+		pathPattern: "/v1/docs/{docId}/head",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/head`,
+		pathPrefix: "/v1/docs/{docId}/head",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/head`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "origin",
+		cdnCacheable: false
+	},
+	manifest: {
+		id: "manifest",
+		pathPattern: "/v1/docs/{docId}/manifest@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/manifest@*`,
+		pathPrefix: "/v1/docs/{docId}/manifest@",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/manifest@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-manifest": {
+		id: "layer-manifest",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/manifest@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/manifest@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/manifest@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/manifest@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"page-render": {
+		id: "page-render",
+		pathPattern: "/v1/docs/{docId}/render/pages/*/data@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/render/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/render/pages/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/render/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.render"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"page-render-annotated": {
+		id: "page-render-annotated",
+		pathPattern: "/v1/docs/{docId}/render/annotated/pages/*/data@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/render/annotated/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/render/annotated/pages/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/render/annotated/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.render"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"page-annotations": {
+		id: "page-annotations",
+		pathPattern: "/v1/docs/{docId}/annotations/pages/*/items@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/annotations/pages/*/items@*`,
+		pathPrefix: "/v1/docs/{docId}/annotations/pages/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/annotations/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.annotate.read"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	layout: {
+		id: "layout",
+		pathPattern: "/v1/docs/{docId}/layout@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/layout@*`,
+		pathPrefix: "/v1/docs/{docId}/layout@",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/layout@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	metadata: {
+		id: "metadata",
+		pathPattern: "/v1/docs/{docId}/metadata@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/metadata@*`,
+		pathPrefix: "/v1/docs/{docId}/metadata@",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/metadata@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	actions: {
+		id: "actions",
+		pathPattern: "/v1/docs/{docId}/actions@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/actions@*`,
+		pathPrefix: "/v1/docs/{docId}/actions@",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/actions@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-layout": {
+		id: "layer-layout",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/layout@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/layout@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/layout@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/layout@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-metadata": {
+		id: "layer-metadata",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/metadata@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/metadata@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/metadata@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/metadata@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-actions": {
+		id: "layer-actions",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/actions@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/actions@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/actions@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/actions@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	attachments: {
+		id: "attachments",
+		pathPattern: "/v1/docs/{docId}/attachments@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/attachments@*`,
+		pathPrefix: "/v1/docs/{docId}/attachments@",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/attachments@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"attachment-files": {
+		id: "attachment-files",
+		pathPattern: "/v1/docs/{docId}/attachment-files/*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/attachment-files/*`,
+		pathPrefix: "/v1/docs/{docId}/attachment-files/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/attachment-files/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.download"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-attachments": {
+		id: "layer-attachments",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/attachments@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/attachments@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/attachments@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/attachments@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.open"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-attachment-files": {
+		id: "layer-attachment-files",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/attachment-files/*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/attachment-files/*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/attachment-files/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/attachment-files/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.download"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-page-render": {
+		id: "layer-page-render",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/render/pages/*/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/render/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/render/pages/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/render/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.render"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-page-render-annotated": {
+		id: "layer-page-render-annotated",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/render/annotated/pages/*/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/render/annotated/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/render/annotated/pages/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/render/annotated/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.render"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"page-text": {
+		id: "page-text",
+		pathPattern: "/v1/docs/{docId}/text/pages/*/data@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/text/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/text/pages/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/text/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.text.copy"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-page-text": {
+		id: "layer-page-text",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/text/pages/*/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/text/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/text/pages/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/text/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.text.copy"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"page-geometry": {
+		id: "page-geometry",
+		pathPattern: "/v1/docs/{docId}/geometry/pages/*/data@*",
+		resolvePathPattern: (docId) => `/v1/docs/${docId}/geometry/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/geometry/pages/",
+		resolvePathPrefix: (docId) => `/v1/docs/${docId}/geometry/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.text.select"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-page-geometry": {
+		id: "layer-page-geometry",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/geometry/pages/*/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/geometry/pages/*/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/geometry/pages/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/geometry/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.text.select"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-search-rects": {
+		id: "layer-search-rects",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/search/rects/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/search/rects/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/search/rects/data@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/search/rects/data@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.text.search"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"layer-search-full": {
+		id: "layer-search-full",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/search/full/data@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/search/full/data@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/search/full/data@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/search/full/data@`,
+		requirement: {
+			kind: "all",
+			capabilities: ["doc.text.search", "doc.text.copy"]
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"annotations-read": {
+		id: "annotations-read",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/annotations/pages/*/items@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/annotations/pages/*/items@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/annotations/pages/",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/annotations/pages/`,
+		requirement: {
+			kind: "single",
+			capability: "doc.annotate.read"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	},
+	"download-current": {
+		id: "download-current",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/download",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/download`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/download",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/download`,
+		requirement: {
+			kind: "single",
+			capability: "doc.download"
+		},
+		routeKind: "origin",
+		cdnCacheable: false
+	},
+	"download-versioned": {
+		id: "download-versioned",
+		pathPattern: "/v1/docs/{docId}/layers/{layerName}/download@*",
+		resolvePathPattern: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/download@*`,
+		pathPrefix: "/v1/docs/{docId}/layers/{layerName}/download@",
+		resolvePathPrefix: (docId, layerName = "default") => `/v1/docs/${docId}/layers/${layerName}/download@`,
+		requirement: {
+			kind: "single",
+			capability: "doc.download"
+		},
+		routeKind: "versioned-read",
+		cdnCacheable: true
+	}
+};
+/**
+* True iff the scope grants access to the named resource.
+*
+* Looks up the resource descriptor, then dispatches to
+* `checkCapability` or `checkAnyCapability` based on the requirement
+* shape. Used by both server route guards and the CDN signer.
+*/
+function checkResourceAccess(resourceId, rawScope, pdfBits) {
+	const r = DOC_RESOURCES[resourceId];
+	switch (r.requirement.kind) {
+		case "single": return checkCapability(r.requirement.capability, rawScope, pdfBits);
+		case "any": return checkAnyCapability(r.requirement.capabilities, rawScope, pdfBits);
+		case "all": return r.requirement.capabilities.every((cap) => checkCapability(cap, rawScope, pdfBits));
+	}
+}
+//#endregion
+//#region src/wire/cdn/coverage.ts
+/**
+* Enumerate the CDN-cacheable resources the scope can access. Returns
+* one {@link CdnCoverageEntry} per granted cacheable resource, carrying
+* both the pattern and the prefix so each adapter can pick the
+* projection it needs.
+*
+* Resources that are not cacheable (head, download-current) are
+* filtered out automatically — they're still gated by their
+* `requirement` at the origin route, but the CDN never gets a
+* credential for them.
+*
+* The URL restructure (paths v2) guarantees each cacheable resource
+* type has a distinct prefix, so prefix-matching adapters get
+* per-resource scope enforcement at the edge — a Bunny token signed
+* at `/v1/docs/{id}/render/pages/` can only authorize render bytes,
+* never text or annotations.
+*/
+/**
+* Plane map: the planes each DOC-LEVEL shared resource depends on. A
+* layer token's edge credential covers a resource's prefix iff EVERY listed
+* plane is inherited (`'base'`) in the caller's scopes — the same condition
+* the origin guard enforces (origin is the truth; this grant is the
+* TTL-bounded optimization). Resources absent from this map (head, manifest,
+* every layer-scoped resource) are not plane-gated.
+*
+* `attachment-files` deliberately lists only `attachments` even though its
+* prefix also serves FileAttachment-annotation bytes (an `annotations`-plane
+* read): the origin guard on that route additionally requires `annotations`
+* inherited, and withholding the whole prefix on annotation divergence would
+* break plain attachment-file sharing for the most common divergence. The
+* residual is a warm-edge window bounded by the grant TTL — the same class
+* as every edge grant.
+*/
+const RESOURCE_PLANES = {
+	"page-render": ["content"],
+	"page-text": ["content"],
+	"page-geometry": ["content"],
+	"page-render-annotated": ["content", "annotations"],
+	"page-annotations": ["annotations"],
+	layout: ["layout"],
+	metadata: ["metadata"],
+	actions: ["actions"],
+	attachments: ["attachments"],
+	"attachment-files": ["attachments"]
+};
+function cdnCoverageForScope(rawScope, pdfBits, context) {
+	const out = [];
+	const scopes = context.scopes;
+	for (const id of Object.keys(DOC_RESOURCES)) {
+		const r = DOC_RESOURCES[id];
+		if (!r.cdnCacheable) continue;
+		const planes = RESOURCE_PLANES[id];
+		if (planes && scopes && planes.some((plane) => scopes[plane] === "layer")) continue;
+		if (!checkResourceAccess(id, rawScope, pdfBits)) continue;
+		out.push({
+			resourceId: id,
+			pathPattern: r.resolvePathPattern(context.docId, context.layerName),
+			pathPrefix: r.resolvePathPrefix(context.docId, context.layerName)
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/wire/cdn/applyCdnAccess.ts
+/**
+* Pure function that turns a request path + a `CdnAccessInfo` block
+* into the final URL the SDK should hit, plus any header/cookie side
+* effects to attach. Used by both:
+*   - the @cloudpdf/engine HttpClient (to actually route requests through
+*     the CDN edge when an /access response says it can)
+*   - the smoke/diagnostic inspector (to PREVIEW what the SDK would do
+*     for a given path, with no network)
+*
+* Keeping this in engine-core means cloud-side request routing and
+* server-side test fixtures use the SAME algorithm. If a regression
+* sneaks in, both ends break together.
+*
+* Selection rules
+* ───────────────
+*   1. Resolve the request path to a `DocResourceId` via DOC_RESOURCES
+*      (longest-prefix-match on the resolved `pathPrefix`). Routes
+*      that don't map to a known resource (admin, /access itself) get
+*      `routedToCdn: false` and stay on origin.
+*   2. If `baseUrlOverrides[resourceId]` exists, swap the request's
+*      origin to that CDN origin. If absent, the request stays on
+*      origin — that's how scope narrowing works at the edge: the
+*      server only emits overrides for resources the caller's scope
+*      grants.
+*   3. Find the LONGEST-matching `signedPathPolicies` entry (its
+*      `pathPrefix` is a prefix of the request path). Append its
+*      `queryParams`. No match falls back to `signedQueryParams` if
+*      the adapter emitted a global token.
+*   4. `signedCookies` and `authHeader` are surfaced verbatim — the
+*      HttpClient sets cookies once per session and applies the
+*      header to every CDN request.
+*/
+function applyCdnAccess(input) {
+	const { path, originUrl, docId, layerName, cdn } = input;
+	const resourceId = resolveResourceIdForPath(path, docId, layerName ?? "default");
+	if (!cdn || cdn.adapter === "none") return {
+		url: `${trimRight(originUrl)}${path}`,
+		resourceId,
+		routedToCdn: false,
+		matchedPolicy: null,
+		authHeader: null,
+		cookies: null,
+		fallbackReason: cdn ? "CDN signer is `none` — every request stays on origin." : "No CdnAccessInfo on this session — request stays on origin."
+	};
+	if (!resourceId) return {
+		url: `${trimRight(originUrl)}${path}`,
+		resourceId: null,
+		routedToCdn: false,
+		matchedPolicy: null,
+		authHeader: null,
+		cookies: null,
+		fallbackReason: "Request path does not match any known DOC_RESOURCES route."
+	};
+	const cdnOrigin = cdn.baseUrlOverrides?.[resourceId];
+	if (!cdnOrigin) return {
+		url: `${trimRight(originUrl)}${path}`,
+		resourceId,
+		routedToCdn: false,
+		matchedPolicy: null,
+		authHeader: null,
+		cookies: null,
+		fallbackReason: `No baseUrlOverrides[${resourceId}] — scope does not grant this resource through the CDN.`
+	};
+	const matchedPolicy = (cdn.signedPathPolicies ?? []).filter((p) => path.startsWith(p.pathPrefix)).sort((a, b) => b.pathPrefix.length - a.pathPrefix.length)[0];
+	const url = new URL(`${trimRight(cdnOrigin)}${path}`);
+	if (matchedPolicy) for (const [k, v] of Object.entries(matchedPolicy.queryParams)) url.searchParams.set(k, v);
+	else if (cdn.signedQueryParams) for (const [k, v] of Object.entries(cdn.signedQueryParams)) url.searchParams.set(k, v);
+	return {
+		url: url.toString(),
+		resourceId,
+		routedToCdn: true,
+		matchedPolicy: matchedPolicy ? {
+			pathPrefix: matchedPolicy.pathPrefix,
+			queryParams: matchedPolicy.queryParams
+		} : null,
+		authHeader: cdn.authHeader,
+		cookies: cdn.signedCookies,
+		fallbackReason: ""
+	};
+}
+/**
+* Walk DOC_RESOURCES and pick the entry whose resolved `pathPrefix`
+* is a (longest) prefix of `path`. Returns null when no resource
+* matches — admin routes, /access, /warm fall into this bucket.
+*
+* Each cacheable resource has a DISTINCT prefix (paths v2 invariant),
+* so longest-match is deterministic.
+*/
+function resolveResourceIdForPath(path, docId, layerName) {
+	let best = null;
+	for (const id of Object.keys(DOC_RESOURCES)) {
+		const prefix = DOC_RESOURCES[id].resolvePathPrefix(docId, layerName);
+		if (!path.startsWith(prefix)) continue;
+		if (!best || prefix.length > best.prefixLength) best = {
+			id,
+			prefixLength: prefix.length
+		};
+	}
+	return best?.id ?? null;
+}
+function trimRight(url) {
+	return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+//#endregion
+//#region src/wire/flatten.ts
+const PATH_SEPARATOR = ".";
+function flatten(value, prefix = "") {
+	const out = {};
+	flattenInto(value, prefix, out);
+	return out;
+}
+function flattenInto(value, prefix, out) {
+	if (value === void 0 || value === null) return;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		if (!prefix) throw new Error("flatten: root value must be an object, not a scalar");
+		if (typeof value === "number" && !Number.isFinite(value)) throw new Error(`flatten: non-finite number at "${prefix}"`);
+		out[prefix] = value;
+		return;
+	}
+	if (Array.isArray(value)) throw new Error(`flatten: arrays are not supported (at "${prefix || "<root>"}")`);
+	if (typeof value !== "object") throw new Error(`flatten: unsupported value type at "${prefix || "<root>"}"`);
+	for (const [k, v] of Object.entries(value)) {
+		if (k.includes(PATH_SEPARATOR)) throw new Error(`flatten: object key "${k}" must not contain "${PATH_SEPARATOR}"`);
+		flattenInto(v, prefix ? `${prefix}${PATH_SEPARATOR}${k}` : k, out);
+	}
+}
+/**
+* Inverse of `flatten`. Takes a flat string-or-scalar map and reconstructs a
+* nested object using `.` as the path separator. Values are passed through
+* unchanged — downstream schema validation (e.g. Zod with `.coerce`) is
+* responsible for type coercion from `string` to numbers/booleans when the
+* input came from a token or query string.
+*
+* Throws on conflicting paths (e.g. having both `viewport` and
+* `viewport.kind` in the same input).
+*/
+function unflatten(flat) {
+	const root = {};
+	for (const [key, value] of Object.entries(flat)) {
+		if (value === void 0) continue;
+		if (key.length === 0) throw new Error("unflatten: empty key");
+		if (key.startsWith(PATH_SEPARATOR) || key.endsWith(PATH_SEPARATOR)) throw new Error(`unflatten: key "${key}" must not start or end with "${PATH_SEPARATOR}"`);
+		if (key.includes(`${PATH_SEPARATOR}${PATH_SEPARATOR}`)) throw new Error(`unflatten: key "${key}" must not contain empty segments`);
+		const path = key.split(PATH_SEPARATOR);
+		let cur = root;
+		for (let i = 0; i < path.length - 1; i++) {
+			const seg = path[i];
+			const existing = cur[seg];
+			if (existing === void 0) {
+				const next = {};
+				cur[seg] = next;
+				cur = next;
+				continue;
+			}
+			if (existing === null || typeof existing !== "object" || Array.isArray(existing)) throw new Error(`unflatten: conflicting paths at "${path.slice(0, i + 1).join(PATH_SEPARATOR)}"`);
+			cur = existing;
+		}
+		const leaf = path[path.length - 1];
+		if (cur[leaf] !== void 0) throw new Error(`unflatten: duplicate key "${key}"`);
+		cur[leaf] = value;
+	}
+	return root;
+}
+//#endregion
+//#region src/wire/renderOptionsCodec.ts
+/**
+* Project image render options plus cache versions into the flat wire shape
+* the render token encoder consumes. The output is a generic dotted-key map
+* (`viewport.kind`, `target.rect.left`, …) — the schema and codec never need
+* to know about specific option fields. Adding a new render option means
+* extending `PageImageOptions`, the render query schemas, and
+* `RenderTokenSchema.fields`; this function does not change.
+*
+* Token/path rule: tokens carry VERSION PINS and RENDER
+* PARAMETERS; anything that changes the artifact's plane-dependency set is
+* PATH-expressed. Annotatedness changes the planes (`content` vs
+* `content + annotations`), so the wire map never carries
+* `includeAnnotations` — the caller picks the path FAMILY
+* (`…/render/pages/` vs `…/render/annotated/pages/`) and passes
+* `annotationVersion` iff it chose the annotated one. Contradictory states
+* are unrepresentable; each family's query schema enforces its own pin
+* grammar structurally.
+*
+* Semantic validation (viewport-kind invariants, per-family pin presence,
+* rect coherence) lives in `PageRenderQuerySchema` /
+* `PageRenderAnnotatedQuerySchema` and runs when the resulting URL is
+* decoded server-side. Round-tripping (flatten → encode → decode →
+* unflatten → schema parse) recovers the original SDK options.
+*/
+function renderImageOptionsToWire(options, versions) {
+	const { includeAnnotations: _pathExpressed, ...wireOptions } = options;
+	return flatten({
+		...wireOptions,
+		contentVersion: versions.contentVersion,
+		...versions.annotationVersion !== void 0 ? { annotationVersion: versions.annotationVersion } : {}
+	});
+}
+/**
+* Convenience: build the full encoded render token in one call. Equivalent
+* to `encodeRenderToken(renderImageOptionsToWire(options, versions))`.
+*/
+function renderImageOptionsToToken(options, versions) {
+	return encodeRenderToken(renderImageOptionsToWire(options, versions));
+}
+/**
+* Re-attach `includeAnnotations` onto the worker-side `PageRenderOptions`
+* shape. Pure shape transform; consumed by the server route after
+* `PageRenderQuerySchema` has produced the SDK-shaped options.
+*/
+function pageRenderOptionsFromImageOptions(options, includeAnnotations) {
+	return {
+		...options.target ? { target: options.target } : {},
+		...options.viewport ? { viewport: options.viewport } : {},
+		...options.rotation !== void 0 ? { rotation: options.rotation } : {},
+		...options.background !== void 0 ? { background: options.background } : {},
+		includeAnnotations
+	};
+}
+/**
+* Project annotation-appearance image options plus the annotation version
+* into the flat wire shape the appearance render token encoder consumes.
+* Mirrors {@link renderImageOptionsToWire}.
+*/
+function annotationAppearancesImageOptionsToWire(options, versions) {
+	return flatten({
+		...options,
+		annotationVersion: versions.annotationVersion
+	});
+}
+/** Convenience: build the full encoded appearance render token in one call. */
+function annotationAppearancesImageOptionsToToken(options, versions) {
+	return encodeAnnotationAppearancesRenderToken(annotationAppearancesImageOptionsToWire(options, versions));
+}
+/**
+* Strip image-encoding fields, leaving the worker-side
+* `AnnotationAppearanceRenderOptions`. Pure shape transform consumed by the
+* server route after `AnnotationAppearancesQuerySchema` produces the
+* SDK-shaped options.
+*/
+function annotationRenderOptionsFromImageOptions(options) {
+	return {
+		...options.scale !== void 0 ? { scale: options.scale } : {},
+		...options.rotation !== void 0 ? { rotation: options.rotation } : {},
+		...options.modes ? { modes: options.modes } : {}
+	};
+}
+//#endregion
+export { ANNOTATION_KINDS, AccessRequestSchema, AccessResponseSchema, ActionsTokenSchema, AnnotationAppearanceManifestSchema, AnnotationAppearancesQuerySchema, AnnotationAppearancesRenderTokenSchema, AnnotationBaseShape, AnnotationBorderStyleSchema, AnnotationCreateResultSchema, AnnotationDTOSchema, AnnotationDeleteResultSchema, AnnotationDraftBaseShape, AnnotationDraftSchema, AnnotationFlagsPartialSchema, AnnotationFlagsSchema, AnnotationListMutationMetaSchema, AnnotationListPageSnapshotSchema, AnnotationListSnapshotAllPagesSchema, AnnotationMoveResultSchema, AnnotationPatchBaseShape, AnnotationPatchSchema, AnnotationRefSchema, AnnotationStableIdSchema, AnnotationTokenSchema, AnnotationUpdateResultSchema, AppearanceOutcomeSchema, AttachmentCreateResultSchema, AttachmentDeleteResultSchema, AttachmentFileInfoSchema, AttachmentsCacheSchema, BlendModeSchema, CacheDeltaSchema, CachePinsSchema, CalloutLineSchema, CaretDTOSchema, CaretDraftSchema, CaretIntentSchema, CaretPatchSchema, CircleDTOSchema, CircleDraftSchema, CirclePatchSchema, ColorSchema, ContentTokenSchema, DEFAULT_LAYER_NAME, DOC_RESOURCES, DocTokenSchema, DocumentActionsSnapshotSchema, DocumentHeadSchema, DocumentManifestSchema, DocumentMetadataSchema, DocumentSecurityStateSchema, EmbeddedFileItemSchema, EmbeddedFileRefSchema, EngineErrorPayloadSchema, FileAttachmentDTOSchema, FileAttachmentIconSchema, FileAttachmentPatchSchema, FileAttachmentWireDraftSchema, FormDataFormatSchema, FormEffectSchema, FormEffectsResultSchema, FormFieldCreateResultSchema, FormFieldDTOSchema, FormFieldDeleteResultSchema, FormFieldDraftSchema, FormFieldFlagsSchema, FormFieldOptionInputSchema, FormFieldOptionSchema, FormFieldPatchSchema, FormFieldRefSchema, FormFieldUpdateResultSchema, FormFieldValueSchema, FormImportResultSchema, FormKindSchema, FormRepairResultSchema, FormSetValueResultSchema, FormSnapshotSchema, FormValueEntrySchema, FormWidgetLinkResultSchema, FormWidgetRefSchema, FreeTextDTOSchema, FreeTextDraftSchema, FreeTextIntentSchema, FreeTextPatchSchema, HighlightDTOSchema, HighlightDraftSchema, HighlightPatchSchema, InkDTOSchema, InkDraftSchema, InkIntentSchema, InkListSchema, InkPatchSchema, KIND_BY_SUBTYPE, LayerScopesSchema, LayoutTokenSchema, LineDTOSchema, LineDraftSchema, LineEndingSchema, LineEndingsSchema, LinePatchSchema, LinePointsSchema, LinkDTOSchema, LinkDraftSchema, LinkPatchSchema, ManifestPageSchema, MetadataPatchSchema, MetadataTokenSchema, MetadataUpdateResultSchema, MutationMetaSchema, NoteIconSchema, OpenDocumentResponseSchema, PageBoxesSchema, PageDeleteInputSchema, PageDeleteResultSchema, PageFlattenInputSchema, PageFlattenResultSchema, PageGeometrySnapshotSchema, PageLayoutSchema, PageListSnapshotSchema, PageMoveInputSchema, PageMoveResultSchema, PageNetworkRenderFormatSchema, PageRenderAnnotatedQuerySchema, PageRenderQuerySchema, PageRotateInputSchema, PageRotateResultSchema, PageStateSchema, PageStructureCacheSchema, PageTextSnapshotSchema, PdfActionNodeSchema, PdfActionTreeSchema, PdfActionTypeSchema, PdfAnnotationActionsSchema, PdfDestinationSchema, PdfFieldActionsSchema, PdfLinkTargetSchema, PdfLinkTargetWritableSchema, PdfPageActionsSchema, PdfPointSchema, PdfQuadSchema, PdfRectDifferencesSchema, PdfRectSchema, PdfRotationSchema, PdfSaveModeSchema, PdfSizeSchema, PointSchema, PolygonDTOSchema, PolygonDraftSchema, PolygonPatchSchema, PolylineDTOSchema, PolylineDraftSchema, PolylinePatchSchema, RectSchema, RedactionApplyResultSchema, RedactionApplyScopeSchema, RefetchReasonSchema, RenderTokenSchema, ResourceRefSchema, RevisionTokenSchema, SearchMatchSchema, SearchModeSchema, SearchQuerySchema, SearchRequestSchema, SearchSliceSchema, SearchSnippetSchema, SearchTokenSchema, SquareDTOSchema, SquareDraftSchema, SquarePatchSchema, SquigglyDTOSchema, SquigglyDraftSchema, SquigglyPatchSchema, StampDTOSchema, StampWireDraftSchema, StampWirePatchSchema, StandardFontSchema, StrikeoutDTOSchema, StrikeoutDraftSchema, StrikeoutIntentSchema, StrikeoutPatchSchema, TextAlignmentSchema, TextDTOSchema, TextDraftSchema, TextPatchSchema, ToggleFieldWidgetSchema, UnderlineDTOSchema, UnderlineDraftSchema, UnderlinePatchSchema, UnsupportedDTOSchema, UnsupportedDraftSchema, UnsupportedPatchSchema, WeakAnnotationSessionPagesRequestSchema, WeakAnnotationSessionResponseSchema, WidgetAppearanceSchema, WidgetPlacementSchema, WireAttachmentFileSchema, annotationAppearancesImageOptionsToToken, annotationAppearancesImageOptionsToWire, annotationRenderOptionsFromImageOptions, applyCdnAccess, cdnCoverageForScope, checkResourceAccess, decodeActionsToken, decodeAnnotationAppearancesRenderToken, decodeAnnotationToken, decodeAttachmentsToken, decodeContentToken, decodeDocToken, decodeDownloadToken, decodeLayoutToken, decodeMetadataToken, decodeRenderToken, decodeSearchToken, decodeToken, decodeTokenText, encodeActionsToken, encodeAnnotationAppearancesRenderToken, encodeAnnotationToken, encodeAttachmentsToken, encodeContentToken, encodeDocToken, encodeDownloadToken, encodeLayoutToken, encodeMetadataToken, encodeRenderToken, encodeSearchToken, encodeToken, encodeTokenText, flatten, pageRenderOptionsFromImageOptions, renderImageOptionsToToken, renderImageOptionsToWire, resolveResourceIdForPath, unflatten, wirePaths };
+
+//# sourceMappingURL=wire.js.map