@inspectorhub/field-ui 0.0.0-stage → 0.1.0

package/dist/data-source-B_ogNIa3.d.ts

@@ -0,0 +1,1519 @@
+import * as Y from 'yjs';
+
+/**
+ * Date/time SHAPE resolution — see #270. Sibling to server/lib/locale.ts and
+ * server/lib/tz.ts, and the third of the four independent display preferences
+ * (language, timezone, currency, shape).
+ *
+ * Shape is its own axis because no locale expresses "English words, American
+ * order, 24-hour clock", and that is a normal field preference: 14:30 is
+ * unambiguous over a radio where "2:30" is not.
+ *
+ * Resolution is per FIELD, not per object. A user who set only the clock keeps
+ * the tenant's date order; collapsing to a per-object choice silently reverts a
+ * preference the user did set.
+ *
+ * The drizzle `{ enum: [...] }` is type-layer only — D1 stores plain TEXT with
+ * no CHECK constraint — so an unrecognized stored value falls back rather than
+ * reaching `Intl` as an unknown key.
+ */
+declare const DATE_FORMATS: readonly ["us", "iso", "eu"];
+declare const TIME_FORMATS: readonly ["12h", "24h"];
+type DateFormat = (typeof DATE_FORMATS)[number];
+type TimeFormat = (typeof TIME_FORMATS)[number];
+
+/** Item types — `rich` is the headline interactive type (rating + three
+ *  canned-comment tabs). The 8 simpler types cover non-rated data points
+ *  the editor surfaces (booleans, numbers with min/max/unit, single- and
+ *  multi-select with choices, date pickers, photo-only fields, and plain
+ *  text / textarea inputs). */
+type ItemType = 'rich' | 'text' | 'boolean' | 'textarea' | 'number' | 'select' | 'multi_select' | 'date' | 'photo_only';
+
+interface PublishBlockingDefect {
+    sectionId: string;
+    sectionTitle: string;
+    itemId: string;
+    itemLabel: string;
+    cannedId: string;
+    cannedTitle: string;
+    missing: Array<'location' | 'trade'>;
+    unresolvedTokens: string[];
+}
+interface PublishReadiness {
+    ready: boolean;
+    blockingDefects: PublishBlockingDefect[];
+    /** Track H (IA-7) — gaps below the tenant's required threshold: shown as
+     *  yellow warnings, never block. Optional so stale server responses
+     *  (pre-split) still type-check. */
+    warningDefects?: PublishBlockingDefect[];
+}
+
+/**
+ * Pure structural-edit snapshot operations for inspection template editing (D8).
+ *
+ * All functions are pure: they never mutate their inputs, always return a new
+ * Snapshot, and every mutator passes its result through stripRuntimeKeys so the
+ * output is persist-ready (matches the strict Zod template schema).
+ *
+ * NO React, NO DB imports — this module may run in any JS environment.
+ */
+
+type Snapshot = {
+    schemaVersion: 2;
+    sections: Section[];
+    ratingSystem?: unknown;
+    [k: string]: unknown;
+};
+type Section = {
+    id: string;
+    title: string;
+    items: Item[];
+    [k: string]: unknown;
+};
+type Item = {
+    id: string;
+    label: string;
+    type: ItemType;
+    parentId?: string | null;
+    [k: string]: unknown;
+};
+
+interface PropertyMetaField {
+    id: string;
+    label: string;
+    type: 'text' | 'number' | 'select' | 'boolean' | 'date';
+    group?: string;
+    required?: boolean;
+    unit?: string;
+    options?: string[];
+}
+
+/**
+ * Commercial PCA Phase S — editable narrative blocks for the report.
+ *
+ * Stored as the `pca_narrative` JSON column on `inspections`. Each block is a
+ * free-prose region (textarea, NO RTE per the project notes=textarea rule)
+ * seeded with ASTM-appropriate default copy so a fresh report is presentable
+ * with zero editing. `userReliance` + `deviations` are STRUCTURED (Phase M /
+ * the deviations store), not free prose, so they are not keys here.
+ *
+ * Pre-launch: the first-cut 5-block shape is RESET, not migrated — the resolver
+ * just ignores unknown/old keys and falls back to seed.
+ */
+interface PcaNarrative {
+    transmittalLetter: string;
+    summaryGeneralDescription: string;
+    summaryPhysicalCondition: string;
+    summaryRecommendations: string;
+    purpose: string;
+    scopeOfWork: string;
+    limitationsExceptions: string;
+    reconnaissance: string;
+    additionalConsiderations: string;
+}
+
+type AutoAdvanceMode = 'always' | 'keyboard' | 'off';
+
+/**
+ * Media Studio — flatten the Media Center API ({attached, pool}) into one
+ * deduped, labeled photo list for the gallery + cover picker. Dedup by R2 key.
+ */
+interface GalleryPhoto {
+    key: string;
+    url: string;
+    label: string;
+    itemId?: string | undefined;
+    photoIndex?: number | undefined;
+    annotated?: boolean | undefined;
+    originalKey?: string | undefined;
+    defectId?: string | undefined;
+    /** Plan 4 — the baked cropped derivative key, when this photo has one. */
+    croppedKey?: string;
+    /** Plan 7 — media discriminator. Absent ⇒ treated as 'photo'. */
+    mediaType?: "photo" | "video";
+    /** Plan 7 — video backend provider. 'stream' = Cloudflare Stream; 'r2' = R2 bucket. */
+    provider?: "stream" | "r2";
+    /** Plan 7 — Cloudflare Stream UID (Stream videos only). */
+    streamUid?: string;
+    /** Plan 7 — pool row id / media id (R2 videos: used to build r2-object URLs). */
+    mediaId?: string;
+    /** Plan 7 — poster timestamp as a fraction of duration (0..1). */
+    posterPct?: number;
+    /** Plan 7 — video duration in seconds (for the m:ss strip badge). */
+    durationSec?: number;
+    /**
+     * #181 PR-G — this photo (or its crop/annotate derivative) is still uploading
+     * from the local offline pending store. The strip/viewer shows an "uploading"
+     * affordance. `url` points at the LOCAL objectURL when this client owns the
+     * blob; when `pendingPlaceholder` is also set the blob lives on ANOTHER device
+     * and there is nothing local to render (show a placeholder, not a broken image).
+     */
+    pending?: boolean;
+    /** #181 PR-G — pending entry whose blob is on another device (no local URL). */
+    pendingPlaceholder?: boolean;
+}
+
+/**
+ * Single source of truth for the `inspection_results.data` JSON projection.
+ *
+ * A Yjs Durable Object will materialize this shape as its authoritative
+ * projection so that all existing readers (report service, PDF renderer, etc.)
+ * remain unchanged when the bespoke per-field-CAS path is retired.
+ *
+ * IMPORTANT — what is NOT here by design:
+ *   The per-field CAS metadata (<field>_v / <field>_by / <field>_at,
+ *   _lastWriter, _lastWriteAt) is intentionally excluded from this projection
+ *   shape. Those fields are part of the bespoke conflict-detection layer that
+ *   the Yjs CRDT migration retires (see #181). They live in the raw
+ *   inspection_results.data blob today but must not leak into the stable
+ *   Yjs-projected view.
+ */
+/** Re-editable crop transform (source-pixel coords) baked into a cropped photo. */
+interface PhotoCropTransform$1 {
+    aspect: string;
+    orientation: 'landscape' | 'portrait';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A photo / video attachment stored inside an inspection result. */
+interface PhotoEntry {
+    key: string;
+    croppedKey?: string;
+    /** Re-editable crop transform recorded alongside `croppedKey`. */
+    crop?: PhotoCropTransform$1;
+    annotatedKey?: string;
+    annotationsJson?: string;
+    mediaType?: 'photo' | 'video';
+    provider?: 'stream' | 'r2';
+    streamUid?: string;
+    mediaId?: string;
+    posterKey?: string;
+    posterPct?: number;
+    durationSec?: number;
+    /** #181 PR-G — true while the binary is only in the local pending store (not yet on R2). */
+    pendingUpload?: boolean;
+    /** #181 PR-G — id into the local media-pending IndexedDB store; resolves to a local blob URL. */
+    pendingId?: string;
+    /**
+     * #181 PR-G — which offline operation produced this pending entry. `'photo'`
+     * is a brand-new offline photo (paired with `pendingUpload: true` + an empty
+     * `key`, so the report skips it). `'crop'` / `'annotate'` are offline
+     * derivatives of an EXISTING photo: the base `key` is KEPT (and serves the
+     * report as an honest fallback) and `pendingUpload` is NOT set, while the
+     * editor shows the local derivative preview until the upload drains.
+     */
+    pendingKind?: 'photo' | 'crop' | 'annotate';
+}
+/** Toggle-state for a single canned information or limitation comment. */
+interface CannedState {
+    cannedId: string;
+    included: boolean;
+    comment?: string | null;
+}
+/**
+ * Snapshot of a repair item attached to a finding.
+ *
+ * Read by `server/lib/aggregate-recommendations.ts`
+ * (`aggregateAttachedRecommendations`, the `GET /:id/recommendations` list).
+ *
+ * `estimateSnapshotMin` / `estimateSnapshotMax` are LEGACY and OPTIONAL: they
+ * exist on findings recorded while repair items still carried a catalogue
+ * price. Nothing writes them any more — the editor's authoring type
+ * (`AttachedRepairItem`, packages/field-ui/src/shared/findings-shared.ts) has no such field, and a
+ * repair item snapshots scope, not a figure. They stay declared so a document
+ * written before the change still parses; do not reintroduce them as a write
+ * path (`scripts/check-price-capability.mjs` holds the line).
+ */
+interface RepairItemSnapshot {
+    recommendationId: string;
+    /** @deprecated legacy read-only; never written. */
+    estimateSnapshotMin?: number | null;
+    /** @deprecated legacy read-only; never written. */
+    estimateSnapshotMax?: number | null;
+    summarySnapshot: string;
+    contractorTypeSnapshot: string | null;
+    attachedAt: number;
+}
+/**
+ * A per-inspection custom comment (inspector free-text, not from the library).
+ *
+ * Read by `server/services/inspection/inspection-report.service.ts`
+ * (`mapCustomDefectsForReport` reads `res.customComments.defects`).
+ */
+interface CustomCommentEntry {
+    id: string;
+    title: string;
+    comment: string;
+    included: boolean;
+    category?: string;
+    location?: string;
+    /** One of `DEFECT_TRADES` (`packages/field-ui/src/shared/defect-fields.types.ts`), or null.
+     *  Same field, same vocabulary and same sanitizer rule as `DefectState.trade`:
+     *  a hand-written defect states WHO should fix it exactly as a canned one
+     *  does, and the contractor-facing repair list reads both by this key. Typed
+     *  `string` rather than `DefectTrade` because this projection describes what
+     *  the JSON blob may hold, not what the write path accepts — the guard in
+     *  `sanitizeDefectStates` is what narrows it. */
+    trade?: string | null;
+    photos?: PhotoEntry[];
+}
+/**
+ * Toggle-state for a single canned defect, with per-defect overrides.
+ *
+ * A defect states WHAT is wrong and WHO should look at it — category, trade,
+ * deadline, timeframe. It carries no repair price: `estimateLow` /
+ * `estimateHigh` were removed, `projectResults` drops them on the way to D1,
+ * and `sanitizeDefectStates` drops them on the way in. Nothing here is a figure
+ * (`scripts/check-price-capability.mjs` holds the line).
+ */
+interface DefectState {
+    cannedId: string;
+    included: boolean;
+    comment?: string | null;
+    /** References a `defect_categories.id` (or a legacy seed name). Widened
+     *  from the former 3-value enum — Authoring unification Plan-4 module K. */
+    category?: string;
+    location?: string | null;
+    photos?: PhotoEntry[];
+    recommendationId?: string | null;
+    trade?: string | null;
+    deadline?: string | null;
+    timeframe?: string | null;
+}
+/**
+ * Composite finding key for one result entry.
+ * Runtime format: `"_default:{sectionId}:{itemId}"` (via `findingKey()`).
+ */
+type FindingKey = string;
+/**
+ * Per-item result entry — the value stored at each `FindingKey` inside
+ * `inspection_results.data`.
+ *
+ * This is the shape the report service reads verbatim: rating, notes, value,
+ * attributes, tabs (information / limitations / defects), photos, original
+ * (re-inspection snapshot), followupStatus, followupNotes.
+ *
+ * NOTE: the per-field CAS metadata (<field>_v/_by/_at, _lastWriter,
+ * _lastWriteAt) is intentionally NOT part of this projection shape — it is
+ * being retired as part of the Yjs CRDT migration (#181).
+ */
+interface ItemEntry {
+    rating?: string;
+    notes?: string;
+    photos?: PhotoEntry[];
+    /** WHAT should be done (a repair-item slug or label) — never what it costs.
+     *  The former `estimateMin` / `estimateMax` pair is gone; see DefectState. */
+    recommendation?: string;
+    attributes?: Record<string, unknown>;
+    value?: unknown;
+    tabs?: {
+        information?: CannedState[];
+        limitations?: CannedState[];
+        defects?: DefectState[];
+    };
+    /** Re-inspection: snapshot of the original finding before the follow-up. */
+    original?: {
+        rating?: string | null;
+        notes?: string | null;
+        photos?: PhotoEntry[];
+    };
+    /** Re-inspection disposition assigned by the inspector. */
+    followupStatus?: string | null;
+    followupNotes?: string | null;
+    /** Repair items attached to this finding (read by aggregate-recommendations). */
+    recommendations?: RepairItemSnapshot[];
+    /** Per-inspection custom comments, grouped by tab. */
+    customComments?: {
+        information?: CustomCommentEntry[];
+        limitations?: CustomCommentEntry[];
+        defects?: CustomCommentEntry[];
+    };
+}
+/**
+ * The full `inspection_results.data` projection: a map of composite finding
+ * keys to per-item result entries.
+ */
+type ResultsProjection = Record<FindingKey, ItemEntry>;
+
+/** Data types of the host resources (cost lines, repair items, media pool, settings sheet, version history, video). */
+/**
+ * The cost lines of one inspection, as the host's cost-items read answers them. `reserveEnabled` is the
+ * tenant's reserve-schedule switch (it shows the EUL / effective age / RUL fields); a host that cannot
+ * read it answers false, which hides them.
+ */
+interface CostItemsListing {
+    items: CostItemView[];
+    reserveEnabled: boolean;
+}
+/**
+ * One write to the cost lines. `create` answers the stored line's id as `data.id` (the panel swaps its
+ * draft id for it); `update` replaces the stored line by id; `delete` removes it by id.
+ */
+type CostItemWrite = {
+    intent: 'create';
+    item: CostItemView;
+} | {
+    intent: 'update';
+    item: CostItemView;
+} | {
+    intent: 'delete';
+    itemId: string;
+};
+/** One catalogue entry the repair-item picker offers. */
+interface RepairItemOption {
+    id: string;
+    name: string;
+    category: string | null;
+    defaultRepairSummary: string;
+    contractorTypeName: string | null;
+}
+/**
+ * The photos of an inspection as the gallery lists them. `answered` is the difference between "this
+ * inspection has no photos" (answered, empty) and "no answer came back" (not answered): only the first
+ * may be shown as a statement about the inspection.
+ */
+interface MediaPoolListing {
+    photos: GalleryPhoto[];
+    answered: boolean;
+}
+/** One photo the report-cover picker offers. */
+interface CoverPhotoOption {
+    key: string;
+    url: string;
+    label: string;
+}
+/** One report appearance profile the settings sheet offers. Presentational: only its id and name. */
+interface ReportProfileOption {
+    id: string;
+    name: string;
+}
+/**
+ * What the inspection settings sheet reads when it opens. `inspection` is the stored inspection row (null
+ * when the host has none to give); the sheet reads `templateId`, `requireDefectFieldsOverride`,
+ * `profileOverride`, `coverPhotoId` / `coverPhoto` and `coverCrop` off it.
+ */
+interface SettingsSheetData {
+    inspection: Record<string, unknown> | null;
+    templates: TemplateSummary[];
+    photos: CoverPhotoOption[];
+    profiles: ReportProfileOption[];
+}
+/** One stored version of an inspection's report content. */
+interface VersionSnapshotEntry {
+    seq: number;
+    atMs: number;
+    byUserId: string | null;
+    /** Why it was captured; absent on legacy rows. */
+    reason?: 'periodic' | 'manual' | 'connect';
+}
+/** One stored version's content: the per-finding projection a compare diffs against the live results. */
+interface VersionSnapshotContent {
+    projection: ResultsProjection;
+}
+/** The provider-specific reference a video upload is addressed by. */
+type VideoUploadRef = {
+    provider: 'stream';
+    streamUid: string;
+} | {
+    provider: 'r2';
+    mediaId: string;
+    r2Key: string;
+};
+/**
+ * What `video.createUpload` answers: where to send the bytes and the backend reference the upload will
+ * end up under. For r2 the `ref` is a placeholder; the real `mediaId` and `r2Key` come back from the
+ * file upload.
+ */
+interface VideoUploadTicket {
+    uploadURL: string;
+    provider: 'stream' | 'r2';
+    ref: VideoUploadRef;
+}
+/** What `video.finalize` takes: the final reference (r2 may carry the poster frame's key). */
+type VideoFinalizeInput = {
+    provider: 'stream';
+    streamUid: string;
+} | {
+    provider: 'r2';
+    mediaId: string;
+    r2Key: string;
+    posterKey?: string;
+};
+
+/**
+ * Data types of the `FieldDataSource` contract.
+ *
+ * The package may not import from `app/` or `server/` (see
+ * `scripts/check-field-ui-boundary.mjs`). Types that live in `./shared` are
+ * re-exported from there, so the contract and the editor logic share one
+ * definition. The shapes the editor reads that still live in the host
+ * (`packages/field-ui/src/hooks/useInspection.ts`, the inspection-edit loader, server libraries)
+ * are declared here from what `app/routes/inspection-edit/loader.server.ts`
+ * returns and what `app/routes/inspection-edit.tsx` reads off it.
+ */
+
+/** Mirrors `Inspection` in packages/field-ui/src/hooks/useInspection.ts. */
+interface EditorInspection {
+    id: string;
+    propertyAddress?: string;
+    clientName?: string;
+    clientEmail?: string;
+    date?: string;
+    scheduledDate?: string;
+    createdAt?: string;
+    status?: string;
+    reportStatus?: string;
+    propertyType?: string;
+    teamMode?: boolean;
+    paymentRequired?: boolean;
+    agreementRequired?: boolean;
+    /** The loader deletes this from the row and returns it once, top-level. */
+    templateSnapshot?: unknown;
+    /** The loader row is the full inspection record; the editor reads further keys defensively. */
+    [key: string]: unknown;
+}
+/** Mirrors `RatingLevel` in packages/field-ui/src/hooks/useInspection.ts. */
+interface RatingLevel {
+    id: string;
+    label: string;
+    name?: string;
+    abbreviation?: string;
+    color: string;
+    severity?: string;
+    isDefect?: boolean;
+    description?: string;
+    pausesAdvance?: boolean;
+}
+/**
+ * Item bodies carry canned-comment tabs, attributes, options and more; the
+ * editor reads them through narrower local types.
+ */
+type TemplateItemBody = Record<string, unknown>;
+/** Mirrors `SchemaItem` in packages/field-ui/src/hooks/useInspection.ts. */
+interface SchemaItem extends TemplateItemBody {
+    id: string;
+    label: string;
+    name?: string;
+    type: string;
+}
+/** Mirrors `SchemaSection` in packages/field-ui/src/hooks/useInspection.ts. */
+interface SchemaSection {
+    id: string;
+    title: string;
+    name?: string;
+    icon?: string;
+    items: SchemaItem[];
+}
+/** The schema after the loader overlays report-data sections. */
+interface TemplateSchema {
+    sections: SchemaSection[];
+}
+/** Mirrors `ResultMap` in packages/field-ui/src/hooks/useInspection.ts. */
+type ResultMap = Record<string, Record<string, unknown>>;
+/** Mirrors `TagPin` in packages/field-ui/src/components/editor/TagChipRow.tsx. */
+interface TagLibraryEntry {
+    id: string;
+    name: string;
+    color: string;
+}
+/** The loader returns `{ id, name, color }` rows. */
+interface DefectCategory {
+    id: string;
+    name: string;
+    color: string;
+}
+/** Mirrors `UnitScopeRow` in packages/field-ui/src/components/editor/BreadcrumbDropdown.tsx. */
+interface InspectionUnit {
+    id: string;
+    name: string;
+    /** 'building' | 'floor' | 'unit'. */
+    kind: string;
+    /** 'unit' | 'common'. */
+    type: string;
+    parentUnitId: string | null;
+    sortOrder: number;
+}
+interface UnitProgress {
+    units: Array<{
+        unitId: string;
+        rated: number;
+        total: number;
+    }>;
+    commonRated: number;
+    total: number;
+}
+/**
+ * The raw, un-normalised template snapshot structural operations rebuild from.
+ * This is the `Snapshot` the structural operations in `./shared/structure-ops`
+ * take and return, so a snapshot read from the data source feeds them directly.
+ */
+type TemplateSnapshot = Snapshot;
+/**
+ * Source today: `RevisionStatus` in server/lib/statutory/revision-status.ts, which
+ * is NOT moved into the package (it pulls in pdf-lib). The data source computes
+ * it, so this declaration is the package's own contract.
+ */
+type RevisionStatus = {
+    kind: 'current';
+} | {
+    kind: 'superseding_soon';
+    nextVersion: string;
+    from: number;
+} | {
+    kind: 'superseded_elsewhere';
+    nextVersion: string;
+    from: number;
+} | {
+    kind: 'cannot_produce';
+    applicableVersion: string;
+    templateVersion: string;
+} | {
+    kind: 'withdrawn';
+    version: string;
+    /** The server's `WithdrawalReason` union. */
+    reason: string;
+    withdrawnAt: number;
+    replacementVersion: string | null;
+};
+/** Mirrors the local `StatutoryDetails` in loader.server.ts. */
+interface StatutoryDetails {
+    inspectorSignatureDate: string | null;
+    employeePrintedName: string | null;
+    ownerName: string | null;
+    ownerEmail: string | null;
+    ownerMailingAddress: string | null;
+    ownerHomePhone: string | null;
+    ownerWorkPhone: string | null;
+    ownerCellPhone: string | null;
+}
+/** Mirrors the local `StatutoryCoverage` in loader.server.ts. */
+interface StatutoryCoverage {
+    formId: string;
+    formTitle: string;
+    revision: string | null;
+    requiredTotal: number;
+    missing: Array<{
+        field: string;
+        provenance: 'pre_inspection' | 'per_inspection' | 'unknown';
+    }>;
+}
+interface ReportSignoffView {
+    role: 'field_observer' | 'pcr_reviewer';
+    personId: string;
+    name: string;
+    license: string | null;
+    qualificationsRef?: string | null;
+    signedAt?: number;
+    dualRole?: boolean;
+}
+interface PsqView {
+    status: 'sent' | 'received' | 'declined';
+    responses: Record<string, unknown> | null;
+}
+interface DocumentReviewItemView {
+    documentKey: string;
+    label: string;
+    requested: boolean;
+    received: boolean;
+    reviewed: boolean;
+    na: boolean;
+    notes: string | null;
+}
+interface RelianceText {
+    userReliance: string;
+    pointInTime: string;
+    siteSpecific: string;
+}
+/** What the compliance panel renders. The compliance panel and the editor loader share it. */
+interface CompliancePanelData {
+    reportSignoffs: ReportSignoffView[];
+    psq: PsqView | null;
+    documentReview: DocumentReviewItemView[];
+    conformance: {
+        standard: 'E2018-24';
+        conforms: boolean;
+    };
+    relianceText: RelianceText;
+}
+/** The loader returns the `commercial:<subtype>`-keyed subset of METADATA_PRESETS. */
+type CommercialPresets = Record<string, PropertyMetaField[]>;
+/** Mirrors `ReportLinkTtl` in server/lib/report-link-ttl.ts (server code, not importable here). */
+type ReportLinkTtl = 'never' | {
+    count: number;
+    unit: 'days' | 'months' | 'years';
+};
+/**
+ * The tenant's inspection-editor preferences, as `useInspectionPrefs` reads and
+ * patches them (packages/field-ui/src/hooks/useInspectionPrefs.ts, `InspectionPrefs`).
+ */
+interface InspectionPrefs {
+    cloneDefault: 'rating' | 'rating_notes' | 'all';
+    autoAdvance: AutoAdvanceMode;
+    autoAdvanceDelayMs: number;
+    pinnedTagIds: string[];
+    /** Which defect fields the publish gate requires tenant-wide. */
+    requireDefectFields: 'none' | 'location' | 'trade' | 'both';
+    agentRepairAccess: 'off' | 'read' | 'readwrite';
+    reportLinkTtl: ReportLinkTtl;
+}
+/**
+ * A crop rectangle in source-image pixels, as the editor serialises it to the
+ * crop endpoints (usePhotoOps `cropTransform`: `{ aspect, orientation, ...pixels }`).
+ */
+interface PhotoCropTransform {
+    /** 'free' or a preset such as '3:2'. */
+    aspect: string;
+    orientation: 'landscape' | 'portrait';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The cooling-window signal the publish dialog reads. */
+interface OutboundCoolingWindow {
+    unlockAtMs: number;
+    turnstileSiteKey: string | null;
+}
+/** The Appendix narrative blocks of a commercial (PCA) report; same shape as `PcaNarrative`. */
+type PcaNarrativeData = PcaNarrative;
+/**
+ * One cost line of a commercial report, client-side mirror of the server's
+ * pca-costs shape (server code is not importable here).
+ */
+interface CostItemView {
+    id: string;
+    system: string;
+    component: string;
+    location: string;
+    action: 'repair' | 'replace' | 'further_study';
+    costMethod: 'unit' | 'lump_sum';
+    quantity: number | null;
+    uom: string | null;
+    unitCostCents: number | null;
+    lumpSumCents: number | null;
+    eul: number | null;
+    effAge: number | null;
+    rul: number | null;
+    suggestedRemedy: string;
+    bucket: 'immediate' | 'short_term' | 'long_term';
+    sectionRef: string | null;
+    photoRef: string | null;
+    sortOrder: number;
+}
+/** One template row of the template picker. Mirrors the rows `/resources/template-search` returns. */
+interface TemplateSummary {
+    id: string;
+    name: string;
+}
+/**
+ * One page of the template picker's search. Mirrors the loader of
+ * `app/routes/resources/template-search.tsx`. The host pages by page number
+ * (25 rows per page), not by offset, so the contract does too.
+ */
+interface TemplateSearchResult {
+    templates: TemplateSummary[];
+    hasMore: boolean;
+    page: number;
+    totalPages: number;
+}
+/**
+ * The filters of a canned-comment library read. Every member is optional and an absent or
+ * empty one is not sent. The host serialises the members in their insertion order, so a
+ * caller that sets `sort` before `search` sends them in that order.
+ */
+interface CommentsLibraryQuery {
+    search?: string;
+    /** 'relevance' or a host-defined sort name. */
+    sort?: string;
+    /** 'auto' narrows by the item context below; 'all' ignores it. */
+    filterMode?: string;
+    itemLabel?: string;
+    section?: string;
+    severity?: string;
+    pageSize?: string;
+}
+/** One library row as the host answers it. `lastUsedAt` is present when the host tracks use. */
+interface CommentsLibraryRow {
+    id: string;
+    text: string;
+    category: string | null;
+    severity: string | null;
+    section: string | null;
+    libraryId?: string | null;
+    useCount?: number;
+    lastUsedAt?: string | null;
+}
+/**
+ * What a library save or edit carries. An empty string for `section`, `category` or `itemLabel`
+ * means "none". `severity` is a rating severity or 'all'; the host stores anything else as none.
+ */
+interface CommentsLibraryEntry {
+    text: string;
+    severity: string;
+    section: string;
+    category: string;
+    itemLabel: string;
+    repairSummary?: string;
+    recommendedContractorTypeId?: string;
+}
+/**
+ * One AI writing-assistance request. `assist` asks for a rewrite of `text` (with the item
+ * `context` when there is one); `review` records that a person reviewed the output of call
+ * `aiCallId` for the artifact `artifactId`.
+ */
+type AiAssistInput = {
+    intent: 'assist';
+    payload: {
+        text: string;
+        context?: string;
+    };
+} | {
+    intent: 'review';
+    payload: {
+        artifactId: string;
+        aiCallId: string;
+    };
+};
+/**
+ * What an AI assist or review answers. A successful `assist` carries BOTH the text and the id of the
+ * call that produced it (a suggestion without an id could never be reviewed, so a host answers
+ * `ok: false` instead); a successful `review` carries neither. `error` is the sentence to show.
+ */
+type AiAssistResult = {
+    ok: true;
+    intent: 'assist';
+    text: string;
+    aiCallId: string;
+} | {
+    ok: true;
+    intent: 'review';
+} | {
+    ok: false;
+    error: string;
+};
+
+/**
+ * The write commands the editor issues. One member per route-action intent of
+ * `app/routes/inspection-edit/action.server.ts` (and the two modules it chains
+ * to, `action-statutory.server.ts` and `action-followup.server.ts`).
+ *
+ * NOT in this union, on purpose:
+ * - `upload-photo`. Photo bytes go through `FieldDataSource.media.uploader`
+ *   (online) or `media.store` (offline); see `MediaUploader` in `media-types.ts`.
+ * - The `PATCH`es the editor writes straight into the live results document.
+ */
+type FieldCommand = {
+    type: 'complete';
+}
+/**
+ * `markComplete` absent or false skips the complete call. `autoSignOnPublish`
+ * ABSENT means "do not touch the stored flag" (the action only PATCHes it when
+ * the form field is present), so a host that has no such toggle must omit it.
+ */
+ | {
+    type: 'publish';
+    markComplete?: boolean;
+    autoSignOnPublish?: boolean;
+    summary?: string;
+}
+/** The body is relayed unchanged to the property-facts PATCH; its keys belong to PropertyInfoForm (Task 5). */
+ | {
+    type: 'save-property-facts';
+    payload: Record<string, unknown>;
+}
+/** Read-only lookup: nothing is persisted. See `CommandDataMap['autofill-property-facts']`. */
+ | {
+    type: 'autofill-property-facts';
+    addressString: string;
+}
+/** The settings sheet's whole form; the data source sanitises it (empty strings mean "unchanged"). */
+ | {
+    type: 'save-settings';
+    payload: Record<string, unknown>;
+}
+/** An empty `key` is refused. */
+ | {
+    type: 'save-pca-narrative';
+    key: string;
+    value: string;
+}
+/** An empty `signatureBase64` is a no-op that still answers ok. */
+ | {
+    type: 'sign-inspector';
+    signatureBase64: string;
+}
+/** An empty string clears the cover. */
+ | {
+    type: 'set-cover';
+    coverPhotoId: string;
+}
+/** Uploads to the media pool, then sets it as the cover. The action requires a `File`; hosts wrap the blob. */
+ | {
+    type: 'upload-cover';
+    file: Blob;
+}
+/** `crop` is the JSON string of a `PhotoCropTransform` (the action forwards it as a form field). */
+ | {
+    type: 'crop-cover';
+    sourceKey: string;
+    crop: string;
+    image: Blob;
+}
+/**
+ * `nodes` is the JSON string of the serialised annotation node tree; always send it (the
+ * action tolerates a missing value by treating it as `'[]'`, which is not part of this
+ * contract). `photoIndex` must be >= 0. `sectionId` is optional: the action omits it
+ * from the request when empty.
+ */
+ | {
+    type: 'annotate';
+    itemId: string;
+    photoIndex: number;
+    nodes: string;
+    image: Blob;
+    sectionId?: string;
+}
+/** `collab` true also asks the live document to converge; a refused convergence answers `ok: false` with `error`. */
+ | {
+    type: 'restructure';
+    snapshot: TemplateSnapshot;
+    collab: boolean;
+} | SaveStructureTemplateCommand | {
+    type: 'add-statutory-instance';
+    groupId: string;
+    index: number;
+    fields: Record<string, unknown>;
+}
+/** Absent keys mean "leave it alone", so a partial payload is safe. */
+ | {
+    type: 'save-statutory-details';
+    payload: Partial<StatutoryDetails>;
+}
+/** `status: null` clears the verdict; an absent `notes` leaves the stored note alone. */
+ | {
+    type: 'set-followup';
+    itemId: string;
+    status: string | null;
+    notes?: string;
+} | UnitCommand | ComplianceCommand
+/** Pulls one unit's findings. See `CommandDataMap['load-scope']`. */
+ | {
+    type: 'load-scope';
+    scope: string;
+};
+/**
+ * `mode: 'new'` forks a template (name defaults to a placeholder when blank).
+ * `mode: 'back'` updates the source template and REQUIRES its id: the action
+ * answers an error without it.
+ */
+type SaveStructureTemplateCommand = {
+    type: 'save-structure-template';
+    mode: 'new';
+    snapshot: TemplateSnapshot;
+    name?: string;
+} | {
+    type: 'save-structure-template';
+    mode: 'back';
+    snapshot: TemplateSnapshot;
+    templateId: string;
+};
+/** Body of the unit bulk-create route (`BulkCreateUnitsSchema`). */
+type BulkCreateUnitsBody = {
+    mode: 'floors_stacks';
+    floors: number[];
+    stacks: number;
+    startAt?: number;
+    parentUnitId?: string | null;
+} | {
+    mode: 'csv';
+    csv: string;
+    parentUnitId?: string | null;
+};
+/**
+ * Per-unit editor mutations (action intents `unit-*`). The payload keys per op
+ * are exactly what each action branch reads:
+ * - create: `name` (trimmed, required; the unit is created top-level)
+ * - rename: `unitId`, `name`
+ * - delete / duplicate: `unitId`
+ * - bulk-create: `payload`, the whole discriminated body
+ * - mode-switch: `mode`
+ * None of them returns data.
+ */
+type UnitCommand = {
+    type: 'unit';
+    op: 'create';
+    name: string;
+} | {
+    type: 'unit';
+    op: 'rename';
+    unitId: string;
+    name: string;
+} | {
+    type: 'unit';
+    op: 'delete';
+    unitId: string;
+} | {
+    type: 'unit';
+    op: 'duplicate';
+    unitId: string;
+} | {
+    type: 'unit';
+    op: 'bulk-create';
+    payload: BulkCreateUnitsBody;
+} | {
+    type: 'unit';
+    op: 'mode-switch';
+    mode: 'tagged' | 'per_unit';
+};
+/**
+ * Compliance panel mutations (action intents `compliance-*`). Keys per op:
+ * - signoff: `role`, `personId`, `name` (all required), `license` (empty becomes null), `dualRole`
+ * - remove-signoff: `role`
+ * - doc-review-seed: none (populates an empty checklist)
+ * - doc-review: `documentKey`, the four flags, `notes` (empty becomes null)
+ * - psq: `responses`
+ * - psq-status: `status`, and `reason` (context carried into the disclosed deviation when declined)
+ */
+type ComplianceCommand = {
+    type: 'compliance';
+    op: 'signoff';
+    role: ReportSignoffView['role'];
+    personId: string;
+    name: string;
+    license: string | null;
+    dualRole: boolean;
+} | {
+    type: 'compliance';
+    op: 'remove-signoff';
+    role: ReportSignoffView['role'];
+} | {
+    type: 'compliance';
+    op: 'doc-review-seed';
+} | {
+    type: 'compliance';
+    op: 'doc-review';
+    documentKey: string;
+    requested: boolean;
+    received: boolean;
+    reviewed: boolean;
+    na: boolean;
+    notes: string | null;
+} | {
+    type: 'compliance';
+    op: 'psq';
+    responses: Record<string, unknown>;
+} | {
+    type: 'compliance';
+    op: 'psq-status';
+    status: PsqView['status'];
+    reason?: string;
+};
+/**
+ * Why an autofill returned no facts. The first three are the property-lookup
+ * service's own codes (`LookupReason`); the last two are the route action's
+ * (address shorter than five characters, and a non-ok API response).
+ */
+type AutofillReason = 'NO_API_KEY' | 'NOT_FOUND' | 'PROVIDER_ERROR' | 'BAD_ADDRESS' | 'REQUEST_FAILED';
+/**
+ * The value a command answers with, keyed by `CommandKey`. A command absent from
+ * this map answers no data. Shapes are what the action returns beside `ok`.
+ */
+interface CommandDataMap {
+    /**
+     * Present on BOTH outcomes: a failed lookup answers `{ ok: false, data: { facts: null, reason } }`,
+     * and a successful lookup that found nothing answers `ok: true` with a `reason`. This is the
+     * channel for the "auto-fill not configured" hint; do not parse `error` for it.
+     */
+    'autofill-property-facts': {
+        facts: Record<string, unknown> | null;
+        reason: AutofillReason | null;
+    };
+    /** The composite-keyed slice for the editor to merge. */
+    'load-scope': {
+        scope: string;
+        results: ResultMap;
+    };
+    /** `coverUrl` is null when the upload response carried none. */
+    'upload-cover': {
+        coverKey: string;
+        coverUrl: string | null;
+    };
+    /** `coverKey` is null when the crop response carried none. */
+    'crop-cover': {
+        coverKey: string | null;
+    };
+    'compliance:signoff': {
+        role: ReportSignoffView['role'];
+    };
+    'compliance:remove-signoff': {
+        role: ReportSignoffView['role'];
+    };
+    'compliance:doc-review': {
+        documentKey: string;
+    };
+    'compliance:psq-status': {
+        status: PsqView['status'];
+    };
+}
+/** `type`, or `type:op` for the two commands that carry an `op`. */
+type CommandKey<C extends FieldCommand> = C extends {
+    type: infer T extends string;
+    op: infer O extends string;
+} ? `${T}:${O}` : C['type'];
+type DataOfKey<K> = K extends keyof CommandDataMap ? CommandDataMap[K] : undefined;
+/** The data type `execute` answers for command `C`; `undefined` when the command returns none. */
+type CommandData<C extends FieldCommand> = DataOfKey<CommandKey<C>>;
+/**
+ * `ok` is the write's outcome. `error` is the sentence to show, when the action
+ * wrote one (publish, restructure, save-structure-template, set-followup,
+ * add-statutory-instance). `data` is typed per command by `CommandDataMap`.
+ */
+interface CommandResult<D = undefined> {
+    ok: boolean;
+    error?: string;
+    data?: D;
+    /**
+     * True on a failure that is NOT a refusal: the host re-sent the command with the same key while the server was
+     * still processing it, and gave up waiting. The write may still land. The caller should say so (the `error` text
+     * does) and must not roll back or retry blindly; checking the inspection shows the real state.
+     */
+    inProgress?: boolean;
+}
+
+/**
+ * What a pending record needs to be attached once its bytes have uploaded. The
+ * `findingKey` is the composite key the results document is keyed by
+ * (`<unit>:<section>:<item>`; `_default` for the common scope), which is how the
+ * drain finds the doc entry to swap the real key into.
+ */
+interface PendingMediaTarget {
+    findingKey: string;
+    itemId: string;
+}
+/**
+ * A photo bound for an item, or for one defect row of an item. Mirrors the
+ * `upload-photo` form fields of the inspection-edit action: `itemId` always;
+ * `customId` and `defectKind` only with `targetType: 'defect'`.
+ */
+type PhotoUploadMeta = (PendingMediaTarget & {
+    targetType: 'item';
+}) | (PendingMediaTarget & {
+    targetType: 'defect';
+    customId: string;
+    defectKind: 'canned' | 'custom';
+});
+/**
+ * A baked crop of an existing photo. Cropping always re-derives from the ORIGINAL `photoKey`.
+ *
+ * `photoKey` is the authority; `photoIndex` is only the position the photo had when the
+ * record was queued. The route addresses a photo by index and does not check the key, so
+ * an uploader MUST re-resolve the index from `findingKey` + `photoKey` against the current
+ * results document at upload time (the web uploader does this in `app/lib/field/web-uploader.ts`) and
+ * must fail the record when the photo is gone, never trust the queued index: a photo
+ * removed while the device was offline would otherwise shift every later index and land
+ * the crop on a different photo. Task 4 owns this when the drain moves into the package.
+ */
+interface PhotoCropMeta extends PendingMediaTarget {
+    photoIndex: number;
+    photoKey: string;
+    crop: PhotoCropTransform;
+    /** Optional on the route; omitted when the item has no section hint. */
+    sectionId?: string;
+}
+/**
+ * A baked annotation layered on a photo. `nodesJson` is the serialised annotation node tree.
+ * `photoKey` is authoritative and `photoIndex` a queued snapshot, exactly as for `PhotoCropMeta`.
+ */
+interface PhotoAnnotateMeta extends PendingMediaTarget {
+    photoIndex: number;
+    photoKey: string;
+    nodesJson: string;
+    sectionId?: string;
+}
+interface PendingMediaBase {
+    pendingId: string;
+    inspectionId: string;
+    blob: Blob;
+    createdAt: number;
+}
+/** `kind` decides which `meta` it carries, so a consumer narrows on `kind` and never casts. */
+type PendingMediaRecord = (PendingMediaBase & {
+    kind: 'photo';
+    meta: PhotoUploadMeta;
+}) | (PendingMediaBase & {
+    kind: 'crop';
+    meta: PhotoCropMeta;
+}) | (PendingMediaBase & {
+    kind: 'annotate';
+    meta: PhotoAnnotateMeta;
+});
+interface PendingMediaStore {
+    /** Must reject on failure. */
+    put(rec: PendingMediaRecord): Promise<void>;
+    get(pendingId: string): Promise<PendingMediaRecord | null>;
+    list(inspectionId?: string): Promise<PendingMediaRecord[]>;
+    delete(pendingId: string): Promise<void>;
+    /** Web: URL.createObjectURL; app: Capacitor.convertFileSrc. */
+    objectUrl(pendingId: string): Promise<string | null>;
+}
+/**
+ * One file's outcome, the same element shape as `results[]` in the
+ * `upload-photo` action's answer (`index` is the file's position in its batch).
+ */
+interface MediaFileResult {
+    index: number;
+    ok: boolean;
+    key?: string;
+    /** `NO_KEY`, `HTTP_<status>` or `EXCEPTION`. */
+    error?: string;
+}
+/**
+ * Online media upload. It is NOT a `FieldCommand`: the editor never routes photo
+ * bytes through `execute`, because a command is a small structured write and
+ * this is a binary body that the offline queue must also be able to replay.
+ *
+ * One call uploads one record (one file). The `upload-photo` action takes a batch
+ * and answers `{ ok, keys: string[], results: MediaFileResult[], itemId, targetType,
+ * customId, defectKind }`; a host that batches maps each file to one `upload` call.
+ * The single `key` / `result` here are that file's outcome: `results[index]` lines up with
+ * the file's position in the batch, while `keys[]` holds only the successful files and is
+ * not aligned with it, so read `results[index].key` rather than `keys[index]`.
+ *
+ * - `kind: 'photo'`: `key` is the stored photo key.
+ * - `kind: 'crop'`: `key` is the derived `croppedKey`.
+ * - `kind: 'annotate'`: `key` is the derived `annotatedKey`.
+ *
+ * Failure is `{ ok: false, error }` and never a throw.
+ */
+interface MediaUploader {
+    upload(rec: PendingMediaRecord): Promise<{
+        ok: true;
+        key: string;
+        result?: MediaFileResult;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+
+/** Everything the editor reads on open. Mirrors the inspection-edit loader's return value. */
+interface EditorData {
+    inspection: EditorInspection;
+    /** The schema with report-data sections overlaid. Never PATCH this; use `templateSnapshot`. */
+    schema: TemplateSchema;
+    results: ResultMap;
+    ratingLevels: RatingLevel[];
+    tagLibrary: TagLibraryEntry[];
+    defectCategories: DefectCategory[];
+    units: InspectionUnit[];
+    unitProgress: UnitProgress;
+    /** 'tagged' is the loader's default; 'per_unit' loads findings per scope. */
+    unitInspectionMode: 'tagged' | 'per_unit';
+    /**
+     * Always an object. The data source supplies the loader's default shape
+     * (`{ schemaVersion: 2, sections: [] }`) when the inspection has no snapshot
+     * (loader.server.ts, the `templateSnapshot` const).
+     */
+    templateSnapshot: TemplateSnapshot;
+    /**
+     * Null for every inspection whose template declares no statutory form, or names
+     * no revision (`revisionStatusForInspection` returns null). Computed by the data
+     * source; the package never imports revision-status (it pulls in pdf-lib).
+     */
+    revisionStatus: RevisionStatus | null;
+    /** Null when the template declares no statutory form, or the read failed (loader: `statutoryDetails`). */
+    statutoryDetails: StatutoryDetails | null;
+    /**
+     * Null means "could not be answered", NOT "nothing is missing" (loader:
+     * `statutoryCoverage`). An empty `missing` array is the other thing.
+     */
+    statutoryCoverage: StatutoryCoverage | null;
+    /**
+     * Always an object: the data source supplies the loader's default shape (empty
+     * sign-offs and checklist, `psq: null`, `conforms: false`) when the inspection
+     * has no compliance rows or the read failed. The route merges
+     * `{ ...compliance, relianceText }`, so a null here would reach the panel as undefined.
+     */
+    compliance: Omit<CompliancePanelData, 'relianceText'>;
+    /** Always an object: the seed-resolved narrative (`resolvePcaNarrative`); the data source supplies the seed. */
+    pcaNarrative: PcaNarrative;
+    /** Always an object: stored text, falling back to the standard boilerplate per field; the data source supplies it. */
+    relianceText: RelianceText;
+    commercialPresets: CommercialPresets;
+    nextPublishIsAmendment: boolean;
+    /** Null unless the session context reports a cooling window. */
+    outboundCoolingWindow: OutboundCoolingWindow | null;
+    /** Null on legacy inspections created before every inspection got a results row. */
+    resultId: string | null;
+    /** The layout band this device showed last time, if the host remembers it: the first frame renders in it, then the viewport decides. Absent means 'desktop'. */
+    initialLayout?: 'phone' | 'tablet' | 'desktop';
+}
+interface SessionInfo {
+    tenantSlug: string | null;
+    /** The company's video backend; the session-context contract always answers one of the two. */
+    videoProvider: 'r2' | 'stream';
+    streamCustomerSubdomain: string | null;
+    collabEditing: boolean;
+    /** Who the viewer is for presence. Null when the host cannot tell: no presence is announced. Never a placeholder shared by several people. */
+    userId: string | null;
+    role: string;
+    /**
+     * The VIEWER's display language: user override, else the tenant default, else
+     * 'en-US' (`useDisplayLocale`). Language follows the viewer on every surface.
+     */
+    locale: string;
+    /**
+     * The VIEWER's display time zone (IANA id): user override, else the tenant's.
+     * Null when the host has none to give; the package then falls back to 'UTC',
+     * which is where `useDisplayTimeZone` ends (the tenant column is NOT NULL
+     * DEFAULT 'UTC', so the web host never answers null).
+     */
+    timeZone: string | null;
+    /**
+     * The VIEWER's date order, resolved per field (user, else tenant, else 'us'),
+     * for workspace chrome (`useChromeDateTimeFormat`). Never use it for a date a
+     * second party also reads.
+     */
+    dateFormat: DateFormat;
+    /** The VIEWER's clock, resolved like `dateFormat`. */
+    timeFormat: TimeFormat;
+    /**
+     * The TENANT's date order, ignoring any personal override: the shape for
+     * inspection, report and appointment dates (`useInspectionDateTimeFormat` /
+     * `useTenantFormatPrefs`). Resolved with the same fallback as `dateFormat`.
+     */
+    tenantDateFormat: DateFormat;
+    /** The TENANT's clock; see `tenantDateFormat`. */
+    tenantTimeFormat: TimeFormat;
+}
+/** What `notify` can say: a neutral note, a success, a degraded outcome that is not a failure, or a failure. */
+type NotifyVariant = 'info' | 'success' | 'warning' | 'error';
+/**
+ * Per-call options of `notify`. `durationMs` replaces the host's default display time for the variant.
+ * `action` adds one button to the message (the editor's "Undo"): `run` is called when it is pressed.
+ */
+interface NotifyOptions {
+    durationMs?: number;
+    action?: {
+        label: string;
+        run: () => void;
+    };
+}
+/**
+ * Per-call options of `execute`. The key is the write's idempotency key; how it reaches the server is the host's
+ * business. The web host sends it as the `idempotencyKey` form field and its route action lifts it to an
+ * `Idempotency-Key` header on the one write of each command that would duplicate a record if repeated (unit create,
+ * statutory instance, cover upload); other commands are idempotent and ignore it. `useFieldCommand` holds the key
+ * across a retry of a failed attempt and rotates it after an `ok` answer; without one `execute` is not idempotent.
+ */
+interface ExecuteOptions {
+    idempotencyKey?: string;
+}
+
+interface ResultsDocHandle {
+    doc: Y.Doc;
+    persistenceSynced: Promise<void>;
+    synced: () => boolean;
+    destroy(): void;
+}
+interface CollabConnector {
+    /** Open a results document: local persistence first, then the network. */
+    connect(inspectionId: string, opts: {
+        onChange?: () => void;
+        onSynced?: () => void;
+    }): ResultsDocHandle;
+    purge(inspectionId: string): Promise<void>;
+}
+interface FieldUrls {
+    photo(inspectionId: string, key: string): string;
+    reportPreview(tenantSlug: string, inspectionId: string): string | null;
+    reportPdf(inspectionId: string): string | null;
+    /** The cost tables' download (`csv` or `xlsx`); a plain link the browser follows. */
+    costExport(inspectionId: string, format: 'csv' | 'xlsx'): string;
+    statutoryPreviewPdf(inspectionId: string): string | null;
+    videoObject(inspectionId: string, ref: string): string | null;
+    /**
+     * The collaborative-presence WebSocket URL (absolute `ws:`/`wss:`). Today
+     * `usePresence` builds it from `window.location`.
+     */
+    presenceSocket(inspectionId: string): string;
+    /** The in-app path of this inspection's editor (the publish dialog reads `window.location.pathname`). */
+    editorPath(inspectionId: string): string;
+    /**
+     * The in-app path of the inspection list, which the header's back control points at. Optional: a host
+     * without addressable pages (a native shell) leaves it out and the control is a plain button that calls
+     * `exit()`. When present the control is a real link (new tab, copy link, link semantics) whose plain
+     * left click still goes through `exit()`, so the host's unsaved-changes guard sees the navigation.
+     */
+    inspectionsList?(): string;
+}
+/**
+ * Optional host capabilities. An absent member hides its entry point.
+ * The `unknown` payloads are tightened by plan B Task 8, which gives each
+ * capability the concrete shape its panel reads.
+ */
+interface FieldResources {
+    /**
+     * The tenant's editor preferences (auto-advance, pinned tags, required defect
+     * fields, ...). Owner: `useInspectionPrefs`, which reads and saves through this
+     * (the web host serves it from `/resources/inspection-prefs`). Absent means the host
+     * has no preference store, and the editor uses its built-in defaults.
+     * `patch` takes a partial delta; a not-ok result means the host did not save it, and
+     * an ok result carries the host's validated, merged preferences as `data`, which the
+     * editor adopts in place of its optimistic copy.
+     */
+    prefs?: {
+        load(): Promise<InspectionPrefs>;
+        patch(delta: Partial<InspectionPrefs>): Promise<CommandResult<InspectionPrefs>>;
+    };
+    /**
+     * The tenant's canned-comment library. Owner: `useCannedComments` (the web host serves it from
+     * `/resources/comments-library`). `list` never rejects: a failed read answers `[]`. `save` creates
+     * an entry, `edit` replaces one, `touch` records one use; a not-ok answer means the host did not
+     * store it. There is no remove: the library page deletes through its own route.
+     */
+    commentsLibrary?: {
+        list(query?: CommentsLibraryQuery): Promise<CommentsLibraryRow[]>;
+        touch(id: string): Promise<CommandResult>;
+        save(entry: CommentsLibraryEntry): Promise<CommandResult>;
+        edit(id: string, entry: CommentsLibraryEntry): Promise<CommandResult>;
+    };
+    /**
+     * The cost lines. `list` never rejects: a failed read answers no lines and no reserve fields. `save`
+     * never rejects either: a refused or unreachable write answers `{ ok: false }`, and a `create` that
+     * landed answers the stored line's id as `data.id`. The caller owns the same-frame guard: a `create`
+     * is not idempotent.
+     */
+    costItems?: {
+        list(inspectionId: string): Promise<CostItemsListing>;
+        save(inspectionId: string, write: CostItemWrite): Promise<CommandResult<{
+            id?: string;
+        }>>;
+    };
+    /** The tenant's repair-item catalogue (it is not per inspection). `list` never rejects: a failed read answers none. */
+    repairItems?: {
+        list(): Promise<RepairItemOption[]>;
+    };
+    /** The inspection's photos for the gallery. `list` never rejects: a failed read answers `answered: false`. */
+    mediaPool?: {
+        list(inspectionId: string): Promise<MediaPoolListing>;
+    };
+    /**
+     * What the inspection settings sheet reads when it opens. Never rejects; `null` means the host could not
+     * read it (the sheet then offers a retry instead of a form that would save blanks over the stored values).
+     */
+    settingsSheet?: {
+        load(inspectionId: string): Promise<SettingsSheetData | null>;
+    };
+    /**
+     * AI writing assistance for an inspection note (the web host serves it from `/resources/ai-assist`).
+     * Never rejects: every failure answers `{ ok: false, error }`. The caller owns the same-frame guard:
+     * an `assist` spends a metered AI call.
+     */
+    aiAssist?: {
+        run(input: AiAssistInput): Promise<AiAssistResult>;
+    };
+    /**
+     * The pre-publish check. `check` never rejects: `null` means the host could not answer (a failed or
+     * unreadable read), and the caller then goes on to the publish dialog rather than blocking on a flaky
+     * pre-flight. A non-null answer is the host's verdict, ready or not. Absent means the host has no
+     * pre-flight and the publish dialog opens directly.
+     */
+    publishReadiness?: {
+        check(inspectionId: string): Promise<PublishReadiness | null>;
+    };
+    /** The template picker's search. Typed from the existing route loader (see `TemplateSearchResult`). */
+    templateSearch?: {
+        search(input: {
+            q: string;
+            page: number;
+        }): Promise<TemplateSearchResult>;
+    };
+    /**
+     * Stored versions of the report content. None of them rejects. A not-ok `list` or `get` means the host
+     * could not read it (the panel shows its retry); a not-ok `restore` carries the sentence to show. The
+     * caller owns the same-frame guard: `capture` and `restore` each store a version row.
+     */
+    versionHistory?: {
+        list(inspectionId: string): Promise<CommandResult<VersionSnapshotEntry[]>>;
+        get(inspectionId: string, seq: number): Promise<CommandResult<VersionSnapshotContent>>;
+        restore(inspectionId: string, seq: number): Promise<CommandResult>;
+        /** The "Save version now" POST. */
+        capture(inspectionId: string): Promise<CommandResult>;
+    };
+    /**
+     * The video upload flow, in the order the capture sheet calls it: `createUpload`, `uploadFile`, (r2)
+     * `uploadPoster`, `finalize`. None of them rejects: a failure answers `{ ok: false, error }` where `error` is
+     * the reason to show, or absent when the host has none (the sheet then shows its own sentence). A host
+     * without the video flow leaves the member out, and the capture entry point is not offered.
+     */
+    video?: {
+        createUpload(inspectionId: string, input: {
+            itemId?: string;
+        }): Promise<CommandResult<VideoUploadTicket>>;
+        /**
+         * Send the clip to the ticket's `uploadURL`, reporting `0..100` progress. For r2 the answer carries the real
+         * `{ mediaId, r2Key }` the finalize needs; for stream it carries no data.
+         */
+        uploadFile(ticket: VideoUploadTicket, file: Blob, onProgress: (pct: number) => void): Promise<CommandResult<{
+            mediaId: string;
+            r2Key: string;
+        } | undefined>>;
+        /** r2 only: store the clip's first frame as its poster. A failure is not fatal to the upload. */
+        uploadPoster(inspectionId: string, ticket: VideoUploadTicket, blob: Blob): Promise<CommandResult<{
+            posterKey: string;
+        }>>;
+        /** Pick the poster frame of a Stream video; `posterPct` is 0..1. */
+        setPoster(inspectionId: string, input: {
+            streamUid: string;
+            posterPct: number;
+        }): Promise<CommandResult>;
+        /** Turn the uploaded clip into a media-pool row; `data.poolId` is that row's id. */
+        finalize(inspectionId: string, input: VideoFinalizeInput): Promise<CommandResult<{
+            poolId: string;
+        }>>;
+        remove(inspectionId: string, ref: string): Promise<CommandResult>;
+    };
+}
+
+interface FieldDataSource {
+    load(inspectionId: string, scope?: string): Promise<EditorData>;
+    session(): SessionInfo;
+    /** The answer's `data` is typed from the command (see `CommandDataMap`). */
+    execute<C extends FieldCommand>(inspectionId: string, cmd: C, opts?: ExecuteOptions): Promise<CommandResult<CommandData<C>>>;
+    /** Show a transient message (replaces the host's toast inside the package). */
+    notify(message: string, variant?: NotifyVariant, opts?: NotifyOptions): void;
+    reload(): void;
+    /**
+     * Start the editor over from a clean mount. `reload()` only re-reads the loader data, but the editor freezes
+     * its template schema (and seeds the collab document from it) when it mounts, so a template change needs a
+     * fresh mount. The web host reloads the page. A host that cannot do this leaves the member out: the editor
+     * then tells the person to reopen the inspection instead of silently showing the old template.
+     */
+    restartSession?(): void;
+    /** Open an address outside the editor (the report preview), in a new tab without an opener on the web. A host that
+     * cannot leaves the member out: the editor then tells the person the preview is unavailable. */
+    openUrl?(url: string): void;
+    exit(): void;
+    isOnline(): boolean;
+    onOnlineChange(cb: (online: boolean) => void): () => void;
+    collab: CollabConnector;
+    media: {
+        store: PendingMediaStore;
+        /**
+         * `doc` is the live results document, or null when the host has none yet. A crop or
+         * annotation addresses its photo by index, so the uploader resolves the CURRENT index from
+         * `doc` at upload time and answers `{ ok: false }` when `doc` is null or the photo is gone.
+         */
+        uploader(inspectionId: string, doc: Y.Doc | null): MediaUploader;
+    };
+    urls: FieldUrls;
+    resources: FieldResources;
+    /** Where the editor runs. It picks the phone and tablet app bar; a native host sets `viewport-fit=cover`, since the native
+     * bars and the bottom tabs reserve `env(safe-area-inset-*)`. The web adapter reports 'web': the bar stays as it was. */
+    platform: 'web' | 'ios' | 'android';
+}
+
+export type { ResultsDocHandle as $, AiAssistInput as A, BulkCreateUnitsBody as B, CommandResult as C, DateFormat as D, EditorData as E, FieldCommand as F, NotifyVariant as G, PcaNarrativeData as H, InspectionPrefs as I, PendingMediaRecord as J, PendingMediaStore as K, PhotoAnnotateMeta as L, MediaFileResult as M, NotifyOptions as N, OutboundCoolingWindow as O, PcaNarrative as P, PhotoCropMeta as Q, PhotoCropTransform as R, PhotoUploadMeta as S, PropertyMetaField as T, PsqView as U, RatingLevel as V, RelianceText as W, RepairItemOption as X, ReportLinkTtl as Y, ReportSignoffView as Z, ResultMap as _, CommandData as a, RevisionStatus as a0, SaveStructureTemplateCommand as a1, SchemaItem as a2, SchemaSection as a3, SessionInfo as a4, SettingsSheetData as a5, StatutoryCoverage as a6, StatutoryDetails as a7, TagLibraryEntry as a8, TemplateItemBody as a9, TemplateSchema as aa, TemplateSearchResult as ab, TemplateSnapshot as ac, TemplateSummary as ad, TimeFormat as ae, UnitCommand as af, UnitProgress as ag, VersionSnapshotContent as ah, VersionSnapshotEntry as ai, VideoFinalizeInput as aj, VideoUploadRef as ak, VideoUploadTicket as al, FieldDataSource as b, AiAssistResult as c, AutoAdvanceMode as d, AutofillReason as e, CollabConnector as f, CommandDataMap as g, CommandKey as h, CommentsLibraryEntry as i, CommentsLibraryQuery as j, CommentsLibraryRow as k, CommercialPresets as l, ComplianceCommand as m, CompliancePanelData as n, CostItemView as o, CostItemWrite as p, CostItemsListing as q, DefectCategory as r, DocumentReviewItemView as s, EditorInspection as t, ExecuteOptions as u, FieldResources as v, FieldUrls as w, InspectionUnit as x, MediaPoolListing as y, MediaUploader as z };