# @embedpdf/engine-core — ./validation AnnotationCopyCreates [InterfaceDeclaration] (from packages/engine/core/src/transfer/planAnnotationCopy.ts): export interface AnnotationCopyCreates{ readonly creates: readonly PlannedCopyCreate[]; readonly dropped: readonly AnnotationImportDrop[]; } AnnotationImportPlan [InterfaceDeclaration] (from packages/engine/core/src/transfer/planAnnotationImport.ts): export interface AnnotationImportPlan{ readonly creates: readonly PlannedAnnotation[]; readonly dropped: readonly AnnotationImportDrop[]; } FormImportPlan [InterfaceDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export interface FormImportPlan{ readonly creates: readonly PlannedFormField[]; readonly calculationOrder: readonly number[]; readonly dropped: readonly FormImportDrop[]; } FormValuesImportTarget [InterfaceDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export interface FormValuesImportTarget{ readonly ref: FormFieldRef; readonly name: string; readonly kind: FormFieldKind; } PlannedAnnotation [InterfaceDeclaration] (from packages/engine/core/src/transfer/planAnnotationImport.ts): export interface PlannedAnnotation{ readonly item: number; readonly page: PageRef; readonly draft: AnnotationDraft; readonly replyTo?:{ readonly planned: number; readonly type: AnnotationReplyType} ; readonly parent?: number; } PlannedCopyCreate [InterfaceDeclaration] (from packages/engine/core/src/transfer/planAnnotationCopy.ts): export interface PlannedCopyCreate extends Omit{ readonly draft: AnnotationDraft; } PlannedFormField [InterfaceDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export interface PlannedFormField{ readonly field: number; readonly draft: FormFieldDraft; readonly widgets: readonly number[]; readonly flags: readonly WidgetFlags[]; readonly value?: FormFieldValue; } PlannedValueWrite [InterfaceDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export interface PlannedValueWrite{ readonly field: number; readonly target: T; readonly value: FormFieldValue; } assertAnnotationDraft [FunctionDeclaration] (from packages/engine/core/src/annotation/checkWrite.ts): export function assertAnnotationDraft( draft: AnnotationDraft, options:{ linked?: readonly string[]; } ={ } , ): void{ const declaration = declarationOf(String(draft.subtype)); const linked = options.linked ?? []; const schema = declaration && linked.length > 0 ? (declaration.fileSchemas.create as unknown as z.AnyZodObject).omit( Object.fromEntries(linked.map((name) => [name, true])), ) : FileAnnotationDraftSchema; const checked = schema.safeParse(draft); if (!checked.success) throw invalidWrite(checked.error, `${ String(draft.subtype)} create`); } assertAnnotationPatch [FunctionDeclaration] (from packages/engine/core/src/annotation/checkWrite.ts): export function assertAnnotationPatch( current: Annotation, prepared: AnnotationPatch, ): void{ const subtype = prepared.subtype ?? current.subtype; if (subtype === 'unsupported') return; const values = prepared as Record; for (const [name, write] of Object.entries(KIND_BY_SUBTYPE[subtype].readBackWrites)){ const value = values[name]; if (value === undefined || write?.safeParse(value).success) continue; throw new EngineError( EngineErrorCode.InvalidArg, write ? `${ subtype} update field '${ name} ': this value can be read but not written; send it back unchanged or replace it` : `${ subtype} update field '${ name} ': the engine works this out; send it back unchanged or leave it out`, { details:{ field: name} } , ); } const parsed = fileAnnotationPatchSchemaOf(subtype).safeParse(prepared); if (!parsed.success) throw invalidWrite(parsed.error, `${ subtype} update`); } pdfResolveAnnotationDraft [FunctionDeclaration] (from packages/engine/core/src/annotation/checkWrite.ts): export function pdfResolveAnnotationDraft( draft: AnnotationDraft, options: DraftResolveOptions ={ } , ): AnnotationDraft{ const prepared = pdfPrepareAnnotationDraft(draft); assertAnnotationDraft(prepared, { linked: options.linked ?? []} ); return pdfDeriveAnnotationDraft(prepared, options); } pdfResolveAnnotationPatch [FunctionDeclaration] (from packages/engine/core/src/annotation/checkWrite.ts): export function pdfResolveAnnotationPatch( current: Annotation, patch: AnnotationPatch, options: ResolveOptions ={ } , ): AnnotationPatch{ const prepared = pdfPrepareAnnotationPatch(current, patch); assertAnnotationPatch(current, prepared); return pdfDeriveAnnotationPatch(current, prepared, options); } planAnnotationCopy [FunctionDeclaration] (from packages/engine/core/src/transfer/planAnnotationCopy.ts): export function planAnnotationCopy( sources: readonly Annotation[], placement: AnnotationCopyPlacement, ): AnnotationCopyCreates{ type Marker ={ field: string; reason: AnnotationDropReason} ; const markers = new Map(); sources.forEach((data, index) =>{ if (data.subtype === 'unsupported' || data.subtype === 'widget') return; const unwritable = unwritableValuesOf(data); markers.set(index, unwritable === 'item' ? 'item' : [...fieldMarkersOf(data), ...unwritable]); } ); const fieldsOf = (index: number): Marker[] =>{ const found = markers.get(index); return found === undefined || found === 'item' ? [] : found; } ; const plan = planAnnotationCopies(sources, placement, (index) => markers.get(index) === 'item'); const creates = plan.copies.map( ({ data, ...copy} ): PlannedCopyCreate => ({ ...copy, draft: draftOf(data, fieldsOf(copy.source), (page) => page, { label: `copy: annotation ${ copy.source} `, details:{ annotation: copy.source} , } ), } ), ); const kept = new Set(creates.map((create) => create.source)); const whole = plan.dropped[Symbol.iterator](); const dropped: AnnotationImportDrop[] = []; sources.forEach((data, index) =>{ if (!kept.has(index)) dropped.push(whole.next().value!); else for (const marker of fieldsOf(index)) dropped.push({ ref: data.ref, ...marker} ); } ); return{ creates, dropped} ; } planAnnotationImport [FunctionDeclaration] (from packages/engine/core/src/transfer/planAnnotationImport.ts): export function planAnnotationImport(input:{ readonly bundle: Pick; readonly pages?: BundleImportPages; readonly target: readonly BundleImportTarget[]; readonly nameTaken: (page: PageRef, nm: string) => boolean; } ): AnnotationImportPlan{ const{ bundle, target, nameTaken} = input; const items = bundle.items.map((item) => item.data); const mapPage = bundlePageMapping({ bundlePages: bundle.pages, pages: input.pages ?? 'same', target, named: items.flatMap(pagesNamedBy), } ); const drops = new Map(); const fieldDrops = new Map>(); const drafts = new Map(); items.forEach((data, index) =>{ if (data.subtype === 'unsupported'){ drops.set(index, 'unsupported-kind'); return; } if (data.subtype === 'widget'){ drops.set(index, 'widget'); return; } if (data.subtype === 'popup' && data.parent === null){ drops.set(index, 'parent-missing'); return; } const unwritable = unwritableValuesOf(data); if (unwritable === 'item'){ drops.set(index, 'unsupported-value'); return; } const markers = [...fieldMarkersOf(data), ...unwritable]; if (markers.length > 0) fieldDrops.set(index, markers); drafts.set( index, draftOf(data, markers, mapPage, { label: `import: item ${ index} `, details:{ item: index} } ), ); } ); const byKey = new Map(); items.forEach((data, index) =>{ const key = annotationKey(data.ref); if (!byKey.has(key)) byKey.set(key, index); } ); const pageOf = (index: number) => encodePageKey(mapPage(items[index]!.ref.page)); const resolve = (ref: AnnotationRef, from: number) =>{ const found = byKey.get(annotationKey(ref)); return found !== undefined && pageOf(found) === pageOf(from) ? found : undefined; } ; const linksOf = (data: Annotation) => [data.reply?.to, data.subtype === 'popup' ? data.parent : null].filter( (ref): ref is AnnotationRef => ref != null, ); items.forEach((data, index) =>{ if (drops.has(index)) return; if (linksOf(data).some((ref) => resolve(ref, index) === undefined)){ drops.set(index, 'parent-missing'); } } ); const popupOf = new Map(); items.forEach((data, index) =>{ if (drops.has(index) || data.subtype !== 'popup' || !data.parent) return; const parent = resolve(data.parent, index)!; if (popupOf.has(parent)) drops.set(index, 'popup-taken'); else popupOf.set(parent, index); } ); const claimed = new Set(); items.forEach((data, index) =>{ if (drops.has(index) || !data.nm) return; const page = mapPage(data.ref.page); const claim = `${ encodePageKey(page)} \u0000${ data.nm} `; if (claimed.has(claim) || nameTaken(page, data.nm)) drops.set(index, 'name-conflict'); else claimed.add(claim); } ); for (let changed = true; changed; ){ changed = false; items.forEach((data, index) =>{ if (drops.has(index)) return; if (linksOf(data).some((ref) => drops.has(resolve(ref, index)!))){ drops.set(index, 'parent-dropped'); changed = true; } } ); } const planned = new Map(); items.forEach((_data, index) =>{ if (!drops.has(index)) planned.set(index, planned.size); } ); const creates: PlannedAnnotation[] = [...planned.keys()].map((index) =>{ const data = items[index]!; const replyTo = data.reply ? planned.get(resolve(data.reply.to, index)!) : undefined; const parent = data.subtype === 'popup' && data.parent ? planned.get(resolve(data.parent, index)!) : undefined; return{ item: index, page: mapPage(data.ref.page), draft: drafts.get(index)!, ...(replyTo !== undefined ?{ replyTo:{ planned: replyTo, type: data.reply!.type} } :{ } ), ...(parent !== undefined ?{ parent} :{ } ), } ; } ); const dropped: AnnotationImportDrop[] = []; items.forEach((data, index) =>{ const reason = drops.get(index); if (reason) dropped.push({ ref: data.ref, reason} ); else for (const drop of fieldDrops.get(index) ?? []) dropped.push({ ref: data.ref, ...drop} ); } ); return{ creates, dropped} ; } planFormCopy [FunctionDeclaration] (from packages/engine/core/src/transfer/planFormCopy.ts): export function planFormCopy(input: Parameters[0]): FormCopyPlan{ const plan = planFormCopies(input); for (const create of plan.creates){ checkedFieldDraft(create.draft, `copy: field ${ create.source} `, { item: create.source} ); } return plan; } planFormImport [FunctionDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export function planFormImport(input:{ readonly bundle: Pick; readonly pages?: BundleImportPages; readonly target: readonly BundleImportTarget[]; readonly nameTaken: (name: string) => boolean; readonly mayScript: boolean; readonly values: boolean; } ): FormImportPlan{ const{ bundle, mayScript} = input; const mapPage = bundlePageMapping({ bundlePages: bundle.pages, pages: input.pages ?? 'same', target: input.target, named: bundle.widgets.flatMap((row) => pageRefsIn(row.data)), } ); const rowByKey = new Map( bundle.widgets.map((row, index) => [annotationKey(row.data.ref), index]), ); const owned = new Set(); const dropped: FormImportDrop[] = []; const claimed = new Set(); const creates: PlannedFormField[] = []; bundle.fields.forEach(({ data: field} , index) =>{ const rows = field.widgets.flatMap((widget) =>{ const row = widget.ref ? rowByKey.get(annotationKey(widget.ref)) : undefined; return row === undefined ? [] : [row]; } ); for (const row of rows) owned.add(row); if (field.kind === 'unknown'){ dropped.push({ ref: field.ref, reason: 'unsupported-kind'} ); return; } if (claimed.has(field.name) || input.nameTaken(field.name)){ dropped.push({ ref: field.ref, reason: 'name-conflict'} ); return; } claimed.add(field.name); const actions = fieldActionsOf(field, mayScript, dropped); const placements = rows.map((row) => widgetPlacementOf(field, bundle.widgets[row]!.data, mapPage, mayScript, dropped), ); const draft = draftOf(field, actions, placements, index); const value = input.values && holdsValue(field) ? fieldValueOf(field) : null; creates.push({ field: index, draft, widgets: rows, flags: rows.map((row) => widgetFlagsOf(bundle.widgets[row]!.data)), ...(value ?{ value} :{ } ), } ); } ); bundle.widgets.forEach((row, index) =>{ if (!owned.has(index)){ dropped.push({ ref: row.data.field, widget: row.data.ref, reason: 'no-field'} ); } } ); const calculationOrder = bundle.calculationOrder.flatMap((ref) =>{ const at = creates.findIndex( (create) => encodeFieldRefKey(bundle.fields[create.field]!.data.ref) === encodeFieldRefKey(ref) && create.draft.actions?.calculate, ); return at < 0 ? [] : [at]; } ); return{ creates, calculationOrder, dropped} ; } planFormValuesImport [FunctionDeclaration] (from packages/engine/core/src/transfer/planFormImport.ts): export function planFormValuesImport(input:{ readonly bundle: Pick; readonly target: readonly T[]; readonly refusal?: ( target: T, value: FormFieldValue, ) => Extract< FormValuesImportDropReason, 'value-not-allowed' | 'locked' | 'fill-not-allowed' > | null; } ):{ readonly writes: readonly PlannedValueWrite[]; readonly dropped: readonly FormValuesImportDrop[]; } { const writes: PlannedValueWrite[] = []; const dropped: FormValuesImportDrop[] = []; input.bundle.fields.forEach(({ data: field} , index) =>{ const value = holdsValue(field) ? fieldValueOf(field) : null; if (!value) return; const target = input.target.find((candidate) => fieldMatches(candidate, { kind: 'fqn', name: field.name} ), ); if (!target){ dropped.push({ ref: field.ref, reason: 'no-field'} ); } else if (target.kind !== field.kind){ dropped.push({ ref: field.ref, reason: 'wrong-kind'} ); } else{ const refused = input.refusal?.(target, value); if (refused) dropped.push({ ref: field.ref, reason: refused} ); else writes.push({ field: index, target, value} ); } } ); return{ writes, dropped} ; }