@inspectorhub/field-ui 0.1.0 → 0.3.0

package/README.md

@@ -4,12 +4,10 @@ The OpenInspection field inspection editor as an embeddable React package, so
 the web app and other hosts (for example the offline-first native client) can
 share one editor.
 
-**Status: pre-1.0 and incomplete.** The package is being extracted from the
-OpenInspection web app in steps. What the published build exports today is the
-host contract (the data source, its types, the provider and hooks, locale
-binding) and an in-memory fake for tests. The editor components themselves are
-not exported yet; this README says so again where it matters, and will change
-when they land.
+**Status: pre-1.0.** The editor page component (`FieldEditor`) is exported,
+together with the host contract it runs on. While the version is below 1.0 a
+minor release can change the exported surface; pin a minor range such as
+`~0.3.0` until 1.0.
 
 ## What the build exports
 
@@ -18,10 +16,79 @@ external):
 
 | Entry | Contents |
 |---|---|
-| `@inspectorhub/field-ui` | `FieldDataSourceProvider`, `useFieldDataSource`, `useFieldCommand`, `useFieldEnsureHuman`, `useFieldSlots`, `isIgnored`, `setFieldLocale`, `bindFieldLocaleSource`, and the TypeScript types of the contract |
+| `@inspectorhub/field-ui` | The editor and the host contract, listed below |
 | `@inspectorhub/field-ui/testing` | `createFakeDataSource` and fakes for each optional resource, for host test suites |
 | `@inspectorhub/field-ui/theme.css` | The design-token and base-layer CSS (see Theme) |
 
+The root entry exports:
+
+| Group | Exports |
+|---|---|
+| The editor | `FieldEditor` (props: `{ data: EditorData }`) |
+| Host contract | `FieldDataSourceProvider`, `useFieldDataSource`, `useFieldCommand`, `useFieldEnsureHuman`, `useFieldSlots`, `isIgnored`, `setFieldLocale`, `bindFieldLocaleSource`, and the TypeScript types of the contract (`FieldDataSource`, `FieldHostSlots`, `FieldUrls`, `FieldResources`, `EditorData`, `SessionInfo`, and so on) |
+| Finding keys | `findingKey`, `findingsForUnit`, `isMetaKey` (the same functions the server uses to address a result) |
+| Photo decoding | `DecodeImageError`, `isDecodeImageError` (matches by error name, so it works across two copies of the package), and the types `DecodeImage`, `DecodeImageOptions`, `DecodedImage` (see `media` below) |
+| Results document | `appendPendingPhoto` (adds a pending photo entry for a file the host stored on the device; needs the finding key and a pending id; adding the same pending id twice leaves one entry), `resolvePendingPhoto` (swaps a pending offline photo entry in the results document for its uploaded key; needs the finding key) |
+| Commercial report text | `resolvePcaNarrative`, `RELIANCE_TEMPLATES`, `METADATA_PRESETS` |
+| Preferences | `DEFAULT_INSPECTION_PREFS` |
+| Overlay stack | `hasOpenLayer`, `escapeWillBeHandled` (see "Back key and open dialogs") |
+| Types | `GalleryPhoto`, `CoverPhotoOption`, `ReportProfileOption`, `VideoUploadRef`, `PublishReadiness`, `PublishBlockingDefect` |
+
+## Mounting the editor
+
+```tsx
+import { FieldDataSourceProvider, FieldEditor, setFieldLocale } from '@inspectorhub/field-ui';
+
+setFieldLocale(session.locale); // and keep it in step with the host's own locale
+
+<FieldDataSourceProvider dataSource={myDataSource} slots={mySlots}>
+  <FieldEditor data={editorData} />
+</FieldDataSourceProvider>
+```
+
+What the host has to provide:
+
+- A `FieldDataSource` (next section). `editorData` is what its `load()` returns.
+  It must follow the host's revalidation: units, publish state and the rest are
+  read from it on every render, so pass the fresh value after each reload.
+- `slots` (`FieldHostSlots`). Publishing is guarded by a human check that fails
+  closed: a host that provides neither `slots.ensureHuman` nor
+  `slots.humanCheck: 'not-required'` gets a check that refuses every send. A
+  host that has no such check by design must write `humanCheck: 'not-required'`
+  down explicitly; leaving the slot out does not turn the gate off.
+- `slots.renderUnsavedGuard`, if leaving the editor with unsaved work should be
+  intercepted. Absent means leaving is never intercepted.
+- The theme (see Theme) and the peer dependencies (see below).
+
+A member of `urls`, `resources` or `slots` that the host leaves out hides the
+entry point that needs it. In particular `urls.costExport` is optional: a host
+without a cost download omits it and the Cost Items panel shows no export
+links.
+
+### Back key and open dialogs
+
+The editor opens dialogs and drawers on an overlay stack that lives inside this
+package (it is bundled, so a host cannot read it from anywhere else). A host
+that handles a hardware back key or a back gesture asks this copy first:
+
+```ts
+import { escapeWillBeHandled, hasOpenLayer } from '@inspectorhub/field-ui';
+
+if (hasOpenLayer()) {
+  // an editor dialog is open: let it consume the key instead of leaving the page
+}
+```
+
+`hasOpenLayer()` is true while any layer is open (dialog, drawer, popover or
+menu). `escapeWillBeHandled()` is true when the next Escape will be taken by an
+overlay.
+
+### Server rendering
+
+The editor is built for a client that renders it. A host that renders on a
+server must give `react-konva` a server stub of its own: the photo annotator
+only renders in the browser.
+
 ## The data source contract
 
 The editor never talks to a server itself. A host implements `FieldDataSource`
@@ -50,6 +117,18 @@ signatures):
 - `collab`: a `CollabConnector` that opens the results Yjs document for an
   inspection (local persistence first, then network).
 - `media`: a `PendingMediaStore` and a `uploader(inspectionId, doc)` factory.
+  Optional `decodeImage(file, opts)` is the host's decoder for a file the browser cannot decode (HEIC/HEIF):
+  - It returns `{ blob }`, an upright JPEG, or `null` to decline (the file is then handled as before).
+  - For a file it recognises but cannot decode it rejects with `DecodeImageError(code, message)`. The `message` is
+    shown to the person and only that file is skipped; the rest of the batch continues. Test for it with
+    `isDecodeImageError(err)` (by `err.name`), not `instanceof`, if the host may hold a second copy of the package.
+  - With keep original on, a HEIC is still converted: `opts.keepOriginal.maxBytes` (10 MiB) asks for full size at the
+    best JPEG quality that fits. Otherwise `opts.maxLongEdge` bounds the size.
+  - Absent, photos behave exactly as in 0.2.1.
+
+  A failed `MediaUploader` result may carry `kept: true`: the host stored the bytes on the device and wrote the
+  pending entry itself with the exported `appendPendingPhoto(doc, findingKey, pendingId)`. The editor then shows a
+  neutral notice and counts the batch as saved, not failed.
 - `urls`: `FieldUrls`, the address builders for photos, reports, presence and
   in-app paths.
 - `resources`: `FieldResources`, optional capabilities (preferences, canned
@@ -58,6 +137,9 @@ signatures):
   host leaves out hides its entry point.
 - `platform`: `'web' | 'ios' | 'android'`.
 
+The `compliance` signoff command's `personId` and `name` are optional (sent together). Absent means the signed-in
+user; the panel shows the two inputs only to an owner or manager, empty.
+
 `FieldHostSlots` carries host-owned UI (theme switch, PDF export, human
 verification). An absent slot hides its entry point.
 
@@ -91,24 +173,28 @@ output. In your global stylesheet:
 
 The editor's photo gallery and lightbox use `react-photo-album` and
 `yet-another-react-lightbox`. Those libraries are peers and their CSS is not
-copied into `dist`. The current build does not import any of them yet (the
-editor components are not exported), so nothing is required today. Once the
-editor components ship, the host must import, from its own copy of each
-library:
-
-```ts
-import 'yet-another-react-lightbox/styles.css';
-import 'react-photo-album/rows.css';
-```
+copied into `dist`. Instead `dist/index.js` keeps two bare side-effect imports,
+`import "react-photo-album/rows.css"` and
+`import "yet-another-react-lightbox/styles.css"`, which your bundler resolves
+from its own copy of each library. The bundler therefore has to handle `.css`
+imports from `node_modules` (Vite and webpack with a CSS loader do). If yours
+does not, import the two files yourself from your global stylesheet entry.
 
 ## Peer dependencies
 
 Declared in `package.json` and resolved by the host so there is one copy of
-each: `react` and `react-dom` ^19, `yjs`, `lib0`, `y-indexeddb`, `y-protocols`,
-`konva`, `react-konva`, `react-easy-crop`, `react-photo-album`, `sortablejs`,
-`yet-another-react-lightbox`. Today only `react` and `yjs` (in
-`/testing`) are imported by the build; the rest are declared ahead of the
-editor components.
+each: `react` and `react-dom` ^19, `yjs`, `lib0`, `y-protocols`, `konva`,
+`react-konva`, `react-easy-crop`, `react-photo-album`, `sortablejs`,
+`yet-another-react-lightbox`. `y-indexeddb` is also declared, but as an
+optional peer: this package never imports it, and only a host that persists the
+results document in the browser through its own `CollabConnector` needs it.
+
+The built root entry imports `react`, `react-dom`, `yjs`, `react-konva` (which
+needs `konva`), `react-easy-crop`, `react-photo-album`, `sortablejs` and
+`yet-another-react-lightbox`, so a host that mounts `FieldEditor` installs all
+of those. `lib0` and `y-protocols` are declared as peers but the built root
+entry does not import them today; they matter to a host that writes its own
+`CollabConnector` on the Yjs sync protocol.
 
 ## Licence
 

package/dist/{data-source-B_ogNIa3.d.ts → data-source-IaWUdrIc.d.ts}

@@ -87,6 +87,7 @@ interface PropertyMetaField {
     unit?: string;
     options?: string[];
 }
+declare const METADATA_PRESETS: Record<string, PropertyMetaField[]>;
 
 /**
  * Commercial PCA Phase S — editable narrative blocks for the report.
@@ -111,6 +112,11 @@ interface PcaNarrative {
     reconnaissance: string;
     additionalConsiderations: string;
 }
+/**
+ * Overlay stored non-empty blocks onto the seed. Empty/whitespace/missing keys
+ * fall back to seed; unknown (old-shape) keys are ignored. Never throws.
+ */
+declare function resolvePcaNarrative(raw: unknown): PcaNarrative;
 
 type AutoAdvanceMode = 'always' | 'keyboard' | 'off';
 
@@ -969,7 +975,7 @@ type UnitCommand = {
 };
 /**
  * Compliance panel mutations (action intents `compliance-*`). Keys per op:
- * - signoff: `role`, `personId`, `name` (all required), `license` (empty becomes null), `dualRole`
+ * - signoff: `role`; `personId` and `name` are optional and sent only together, when an owner or manager records another person (omitted means the signed-in user; the server refuses them from any other role). `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)
@@ -980,8 +986,8 @@ type ComplianceCommand = {
     type: 'compliance';
     op: 'signoff';
     role: ReportSignoffView['role'];
-    personId: string;
-    name: string;
+    personId?: string;
+    name?: string;
     license: string | null;
     dualRole: boolean;
 } | {
@@ -1168,6 +1174,8 @@ interface MediaFileResult {
     key?: string;
     /** `NO_KEY`, `HTTP_<status>` or `EXCEPTION`. */
     error?: string;
+    /** The upload failed but the host kept the bytes on the device (see `MediaUploader`): not a lost photo. */
+    kept?: boolean;
 }
 /**
  * Online media upload. It is NOT a `FieldCommand`: the editor never routes photo
@@ -1185,7 +1193,9 @@ interface MediaFileResult {
  * - `kind: 'crop'`: `key` is the derived `croppedKey`.
  * - `kind: 'annotate'`: `key` is the derived `annotatedKey`.
  *
- * Failure is `{ ok: false, error }` and never a throw.
+ * Failure is `{ ok: false, error }` and never a throw. A host that stored the bytes on the device and wrote the
+ * pending entry itself (see `appendPendingPhoto`) adds `kept: true`: the photo is not lost and uploads later, so the
+ * editor counts it as saved on the device instead of as a failure.
  */
 interface MediaUploader {
     upload(rec: PendingMediaRecord): Promise<{
@@ -1195,9 +1205,35 @@ interface MediaUploader {
     } | {
         ok: false;
         error: string;
+        kept?: true;
     }>;
 }
 
+interface DecodeImageOptions {
+    /** Longest edge the caller will keep; the decoder SHOULD NOT return more pixels than this. Omitted: full size. */
+    maxLongEdge?: number;
+    /**
+     * Present when the person keeps original quality. Return the image at full size and the highest JPEG quality that
+     * keeps the result within `maxBytes`.
+     */
+    keepOriginal?: {
+        maxBytes: number;
+    };
+}
+interface DecodedImage {
+    /** A browser-decodable image (image/jpeg). Orientation already applied; no metadata is required. */
+    blob: Blob;
+}
+/** A file the host recognised but could not decode. `message` is shown to the person, so the host words it. */
+declare class DecodeImageError extends Error {
+    readonly code: 'UNSUPPORTED' | 'TOO_LARGE_PIXELS' | 'CORRUPT' | 'TIMEOUT';
+    constructor(code: DecodeImageError['code'], message: string);
+}
+/** Matched by name rather than by class, so an error from a second copy of this package in the host still counts. */
+declare function isDecodeImageError(e: unknown): e is DecodeImageError;
+/** The optional `media.decodeImage` capability of a data source. */
+type DecodeImage = (file: Blob, opts: DecodeImageOptions) => Promise<DecodedImage | null>;
+
 /** Everything the editor reads on open. Mirrors the inspection-edit loader's return value. */
 interface EditorData {
     inspection: EditorInspection;
@@ -1330,8 +1366,11 @@ 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;
+    /**
+     * The cost tables' download (`csv` or `xlsx`); a plain link the browser follows. Optional: a host with no
+     * such download (a native shell) leaves it out and the Cost Items panel shows no export links.
+     */
+    costExport?(inspectionId: string, format: 'csv' | 'xlsx'): string;
     statutoryPreviewPdf(inspectionId: string): string | null;
     videoObject(inspectionId: string, ref: string): string | null;
     /**
@@ -1508,6 +1547,12 @@ interface FieldDataSource {
          * `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;
+        /**
+         * Optional. Turns a file the browser cannot decode (HEIC/HEIF) into a JPEG the browser can. Return null when this
+         * host cannot decode that file (the caller keeps its own behaviour); reject with `DecodeImageError` for a file
+         * that is recognised but cannot be decoded. Absent: photos behave exactly as before.
+         */
+        decodeImage?: DecodeImage;
     };
     urls: FieldUrls;
     resources: FieldResources;
@@ -1516,4 +1561,5 @@ interface FieldDataSource {
     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 };
+export { METADATA_PRESETS as M, isDecodeImageError as aw, resolvePcaNarrative as ax, DecodeImageError as t };
+export type { PsqView as $, AiAssistInput as A, BulkCreateUnitsBody as B, CommandResult as C, DateFormat as D, EditorData as E, FieldCommand as F, FieldResources as G, FieldUrls as H, InspectionPrefs as I, GalleryPhoto as J, InspectionUnit as K, MediaFileResult as L, MediaPoolListing as N, MediaUploader as O, NotifyOptions as P, NotifyVariant as Q, OutboundCoolingWindow as R, PcaNarrative as S, PcaNarrativeData as T, PendingMediaRecord as U, PendingMediaStore as V, PhotoAnnotateMeta as W, PhotoCropMeta as X, PhotoCropTransform as Y, PhotoUploadMeta as Z, PropertyMetaField as _, CommandData as a, PublishBlockingDefect as a0, PublishReadiness as a1, RatingLevel as a2, RelianceText as a3, RepairItemOption as a4, ReportLinkTtl as a5, ReportProfileOption as a6, ReportSignoffView as a7, ResultMap as a8, ResultsDocHandle as a9, RevisionStatus as aa, SaveStructureTemplateCommand as ab, SchemaItem as ac, SchemaSection as ad, SessionInfo as ae, SettingsSheetData as af, StatutoryCoverage as ag, StatutoryDetails as ah, TagLibraryEntry as ai, TemplateItemBody as aj, TemplateSchema as ak, TemplateSearchResult as al, TemplateSnapshot as am, TemplateSummary as an, TimeFormat as ao, UnitCommand as ap, UnitProgress as aq, VersionSnapshotContent as ar, VersionSnapshotEntry as as, VideoFinalizeInput as at, VideoUploadRef as au, VideoUploadTicket as av, 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, CoverPhotoOption as r, DecodeImage as s, DecodeImageOptions as u, DecodedImage as v, DefectCategory as w, DocumentReviewItemView as x, EditorInspection as y, ExecuteOptions as z };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { F as FieldCommand, C as CommandResult, a as CommandData, b as FieldDataSource } from './data-source-B_ogNIa3.js';
-export { A as AiAssistInput, c as AiAssistResult, d as AutoAdvanceMode, e as AutofillReason, B as BulkCreateUnitsBody, f as CollabConnector, g as CommandDataMap, h as CommandKey, i as CommentsLibraryEntry, j as CommentsLibraryQuery, k as CommentsLibraryRow, l as CommercialPresets, m as ComplianceCommand, n as CompliancePanelData, o as CostItemView, p as CostItemWrite, q as CostItemsListing, D as DateFormat, r as DefectCategory, s as DocumentReviewItemView, E as EditorData, t as EditorInspection, u as ExecuteOptions, v as FieldResources, w as FieldUrls, I as InspectionPrefs, x as InspectionUnit, M as MediaFileResult, y as MediaPoolListing, z as MediaUploader, N as NotifyOptions, G as NotifyVariant, O as OutboundCoolingWindow, P as PcaNarrative, H as PcaNarrativeData, J as PendingMediaRecord, K as PendingMediaStore, L as PhotoAnnotateMeta, Q as PhotoCropMeta, R as PhotoCropTransform, S as PhotoUploadMeta, T as PropertyMetaField, U as PsqView, V as RatingLevel, W as RelianceText, X as RepairItemOption, Y as ReportLinkTtl, Z as ReportSignoffView, _ as ResultMap, $ as ResultsDocHandle, a0 as RevisionStatus, a1 as SaveStructureTemplateCommand, a2 as SchemaItem, a3 as SchemaSection, a4 as SessionInfo, a5 as SettingsSheetData, a6 as StatutoryCoverage, a7 as StatutoryDetails, a8 as TagLibraryEntry, a9 as TemplateItemBody, aa as TemplateSchema, ab as TemplateSearchResult, ac as TemplateSnapshot, ad as TemplateSummary, ae as TimeFormat, af as UnitCommand, ag as UnitProgress, ah as VersionSnapshotContent, ai as VersionSnapshotEntry, aj as VideoFinalizeInput, ak as VideoUploadRef, al as VideoUploadTicket } from './data-source-B_ogNIa3.js';
-import * as react from 'react';
+import { F as FieldCommand, C as CommandResult, a as CommandData, b as FieldDataSource, E as EditorData, I as InspectionPrefs } from './data-source-IaWUdrIc.js';
+export { A as AiAssistInput, c as AiAssistResult, d as AutoAdvanceMode, e as AutofillReason, B as BulkCreateUnitsBody, f as CollabConnector, g as CommandDataMap, h as CommandKey, i as CommentsLibraryEntry, j as CommentsLibraryQuery, k as CommentsLibraryRow, l as CommercialPresets, m as ComplianceCommand, n as CompliancePanelData, o as CostItemView, p as CostItemWrite, q as CostItemsListing, r as CoverPhotoOption, D as DateFormat, s as DecodeImage, t as DecodeImageError, u as DecodeImageOptions, v as DecodedImage, w as DefectCategory, x as DocumentReviewItemView, y as EditorInspection, z as ExecuteOptions, G as FieldResources, H as FieldUrls, J as GalleryPhoto, K as InspectionUnit, M as METADATA_PRESETS, L as MediaFileResult, N as MediaPoolListing, O as MediaUploader, P as NotifyOptions, Q as NotifyVariant, R as OutboundCoolingWindow, S as PcaNarrative, T as PcaNarrativeData, U as PendingMediaRecord, V as PendingMediaStore, W as PhotoAnnotateMeta, X as PhotoCropMeta, Y as PhotoCropTransform, Z as PhotoUploadMeta, _ as PropertyMetaField, $ as PsqView, a0 as PublishBlockingDefect, a1 as PublishReadiness, a2 as RatingLevel, a3 as RelianceText, a4 as RepairItemOption, a5 as ReportLinkTtl, a6 as ReportProfileOption, a7 as ReportSignoffView, a8 as ResultMap, a9 as ResultsDocHandle, aa as RevisionStatus, ab as SaveStructureTemplateCommand, ac as SchemaItem, ad as SchemaSection, ae as SessionInfo, af as SettingsSheetData, ag as StatutoryCoverage, ah as StatutoryDetails, ai as TagLibraryEntry, aj as TemplateItemBody, ak as TemplateSchema, al as TemplateSearchResult, am as TemplateSnapshot, an as TemplateSummary, ao as TimeFormat, ap as UnitCommand, aq as UnitProgress, ar as VersionSnapshotContent, as as VersionSnapshotEntry, at as VideoFinalizeInput, au as VideoUploadRef, av as VideoUploadTicket, aw as isDecodeImageError, ax as resolvePcaNarrative } from './data-source-IaWUdrIc.js';
+import * as React from 'react';
 import { ReactNode } from 'react';
-import 'yjs';
+import * as Y from 'yjs';
 
 /**
  * Host-supplied UI, injected through `FieldDataSourceProvider` rather than read
@@ -60,7 +60,7 @@ interface FieldDataSourceProviderProps {
     slots?: FieldHostSlots;
     children?: ReactNode;
 }
-declare function FieldDataSourceProvider({ dataSource, slots, children }: FieldDataSourceProviderProps): react.JSX.Element;
+declare function FieldDataSourceProvider({ dataSource, slots, children }: FieldDataSourceProviderProps): React.JSX.Element;
 /** The data source of the nearest provider. Throws outside one: a silent null would fail much later. */
 declare function useFieldDataSource(): FieldDataSource;
 /** The host-supplied UI slots; an empty object when the provider was given none. */
@@ -126,6 +126,89 @@ interface FieldCommandRunner {
  */
 declare function useFieldCommand(inspectionId: string): FieldCommandRunner;
 
+/**
+ * The inspection editor page. It reads everything from its `data` prop, the field data source and the host
+ * slots, so any host (web route, native shell) mounts it the same way. `data` must follow the host's
+ * revalidation: units, publish state and the rest are read from it on every render.
+ */
+declare function FieldEditor({ data }: {
+    data: EditorData;
+}): React.JSX.Element;
+
+declare function findingKey(unitId: string | null | undefined, sectionId: string, itemId: string): string;
+declare function findingsForUnit(data: Record<string, unknown>, unitId: string): Record<string, unknown>;
+/**
+ * A meta key of a results blob (`_inspector_signature`): underscore-prefixed with
+ * fewer than three colon-separated parts. It is not a finding, and the results
+ * document never holds it: importing a blob skips it, and projecting a document
+ * skips one an older document may still carry as an empty item map (either would
+ * otherwise replace the real value in the blob with `{}`). Composite finding keys
+ * start with `_default:` too, which is why the prefix alone cannot decide.
+ */
+declare function isMetaKey(key: string): boolean;
+
+/**
+ * Bridges a live Y.Doc (from `use-results-doc.ts`) to the editor's in-memory
+ * ResultMap, and provides write helpers that mirror the editor's existing hook
+ * signatures so Task 9 can swap them in 1:1.
+ *
+ * NO React import. NO import of packages/field-ui/src/hooks/useInspection.ts (React-heavy).
+ */
+
+/**
+ * #181 PR-G — append a brand-new offline photo as a PENDING doc entry.
+ *
+ * The binary is only in the local media-pending store (not yet on R2), so the
+ * entry has an EMPTY `key` + `pendingUpload: true` + the `pendingId` that
+ * resolves to the local blob. The report SKIPS such entries (it filters
+ * `pendingUpload`); the editor renders them from the local objectURL. On drain
+ * the entry is swapped to its real R2 key via `resolvePendingPhoto` below.
+ */
+declare function appendPendingPhoto(doc: Y.Doc, findingKey: string, pendingId: string): void;
+/**
+ * #181 PR-G — resolve a pending photo after its offline blob has uploaded.
+ *
+ * Swaps the doc entry pending→real key and CLEARS the pending markers
+ * (`pendingUpload` / `pendingId` / `pendingKind`) by replace-in-place (field
+ * delete is unsupported). The match key differs by kind:
+ *  - `photo`:    the entry's `key` is empty; match by the entry whose
+ *                `pendingId === pendingId`, then set the real `key` = result.key.
+ *  - `crop`:     match by base `key`, set `croppedKey` = result.croppedKey.
+ *  - `annotate`: match by base `key`, set `annotatedKey` = result.annotatedKey.
+ *
+ * No-op if no matching pending entry is found (idempotent — a duplicate drain
+ * after the swap simply finds nothing).
+ */
+declare function resolvePendingPhoto(doc: Y.Doc, findingKey: string, pendingId: string, kind: 'photo' | 'crop' | 'annotate', photoKey: string | undefined, result: {
+    key?: string;
+    croppedKey?: string;
+    annotatedKey?: string;
+}): void;
+
+/**
+ * Commercial PCA Phase M — seeded reliance / point-in-time / site-specific
+ * disclaimer text (ASTM §4.2.1–4.2.4). Defaults the Phase S §2.5 (User Reliance)
+ * and Limitations regions so the legal boilerplate is never missing; the
+ * inspector may edit it. Plain text (textarea, no RTE — project decision).
+ */
+declare const RELIANCE_TEMPLATES: {
+    readonly userReliance: string;
+    readonly pointInTime: string;
+    readonly siteSpecific: string;
+};
+
+/** What the editor behaves like until the tenant's own preferences arrive (or when the host has no preference store). */
+declare const DEFAULT_INSPECTION_PREFS: InspectionPrefs;
+
+/** True while at least one layer is open. */
+declare function hasOpenLayer(): boolean;
+/**
+ * True when the next Escape will be taken by an overlay. For window-level hotkeys that are
+ * not layers: they must skip Escape exactly when a layer will answer it, and not when a
+ * layer is open that does not answer Escape.
+ */
+declare function escapeWillBeHandled(): boolean;
+
 /**
  * Pin the package to one locale, explicitly.
  *
@@ -151,5 +234,5 @@ declare function setFieldLocale(locale: string): void;
  */
 declare function bindFieldLocaleSource(read: (() => string) | null): void;
 
-export { CommandData, CommandResult, FieldCommand, FieldDataSource, FieldDataSourceProvider, bindFieldLocaleSource, isIgnored, setFieldLocale, useFieldCommand, useFieldDataSource, useFieldEnsureHuman, useFieldSlots };
+export { CommandData, CommandResult, DEFAULT_INSPECTION_PREFS, EditorData, FieldCommand, FieldDataSource, FieldDataSourceProvider, FieldEditor, InspectionPrefs, RELIANCE_TEMPLATES, appendPendingPhoto, bindFieldLocaleSource, escapeWillBeHandled, findingKey, findingsForUnit, hasOpenLayer, isIgnored, isMetaKey, resolvePendingPhoto, setFieldLocale, useFieldCommand, useFieldDataSource, useFieldEnsureHuman, useFieldSlots };
 export type { FieldCommandRunner, FieldDataSourceProviderProps, FieldHostSlots, FieldRunResult, IgnoredRun };