@embedpdf/plugin-annotation 3.0.0-next.14 → 3.0.0-next.16

package/README.md

@@ -0,0 +1,129 @@
+# @embedpdf/plugin-annotation
+
+The annotation plugin: drawing, selecting, moving, restyling, typing into and
+deleting annotations, over a document the engine owns. It wires the pure
+[`@embedpdf/core-annotation`](../../core/annotation/README.md) to the engine
+and to the interaction hub. It has no framework code; the adapters render its
+reads.
+
+## Three kinds of data, one owner each
+
+What the user sees is built from three kinds of data. Each has exactly one
+owner, and nothing else writes it.
+
+| Data          | What it is                                                                                                      | Owner                                                   | Changed by                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
+| **confirmed** | every annotation record the engine confirmed, with its appearance version                                       | the records mirror (`sync/records.ts`), `records.get()` | confirmed document events, from any session, and loads       |
+| **pending**   | this session's changes the engine hasn't answered yet, one per user action                                      | the kernel's change queue (`ctx.changes`)               | a user action stages one; it leaves once the engine answered |
+| **session**   | selection, hover, the gesture in progress, text editing, tool settings, the object numbers held for new records | `session` in the plugin state (`model.ts`)              | the core's `update`                                          |
+
+The records mirror shows the pending changes on top of what the engine
+confirmed (`records.view()`): it replays them, op by op, through
+`predictRecords`, the same rules the engine applies. The **view**
+(`read/view.ts`) turns those records into the core's records, each drawn as
+the change on it says, and composes them with the session into the core's
+`Model`. Every read and every gesture takes that model. It is memoized per
+record, so a change to one record does not recompute the others.
+
+## The life of one change
+
+A user drags a square to a new place:
+
+```
+ pointer up
+    │
+    ▼
+ store.commit({ type: 'editPointer', phase: 'up', … })          services/store.ts
+    │
+    ├─ update(model, message)                                   core-annotation
+    │     → session   (the drag is over)
+    │     → change    (put: the square at its new place)
+    │     → effects   ([{ type: 'patch', id: 'obj:12', patch: { box } }])
+    │
+    ├─ op builders                                              write/ops.ts
+    │     patch → { type: 'annotations.update', ref, patch }
+    │     (an annotation's link children follow it: write/links.ts)
+    │
+    └─ ctx.changes.stage({ label, ops, undo })                  the kernel
+          the records mirror predicts it: the view shows the square at its
+          new place at once. The queue sends it after everything staged
+          before it; the engine applies it, all or nothing, and publishes
+          `annotations.updated` before it answers:
+            the records mirror folds it → confirmed obj:12 is at the new place
+          the change leaves the view → the view shows the confirmed record
+```
+
+One user action is one change: moving five annotations is one change of five
+ops, one request, one undo step. The rules:
+
+- **Refused** (a revoked grant, a lock set elsewhere): the change leaves the
+  view at once, and the view shows the confirmed record, including anything
+  another session changed meanwhile. Nothing has to be undone by hand, and
+  `onWriteFailed` tells the UI why. A change that names a record only a
+  refused change would have created is refused with it.
+- **Applied**: the change leaves the view once the records mirror holds the
+  answer, which is at once when its events folded; if a fold asked to read a
+  page again, the view keeps it until that read lands.
+- **In order**: the engine answers changes in the order they were staged, so
+  a newer change always shows over an older one's answer.
+
+The same pipeline carries every kind of change:
+
+- **New annotations** take an object number the session holds
+  (`services/object-numbers.ts`), so a new record has its final ref from its
+  first frame: it can be selected, edited, linked or deleted at once, and
+  each of those is simply staged after its create. A replace-text caret and
+  its strikeout are two creates in one change, the strikeout answering the
+  caret by its number. Should the document's pool be empty for a moment, the
+  create waits for numbers (the drawing stays on screen).
+- **Deletes**: the record and what goes with it (its replies, grouped parts,
+  popups) leave the view at once, and come back if the engine refuses.
+- **Typing** goes into one held change per pause (`write/text-editing.ts`):
+  every keystroke amends it, so the text shows at once, and it is sent after
+  a pause, when editing ends, when anything else is staged, and before a
+  download. A format on the words selected while typing goes into it too.
+- **Changes stated in code** (`create`, `update`, `delete`, `reorder`,
+  comments, links, scripts) go through the store's second door, `apply`: each
+  is checked with the engine's own functions, shown at once, and sent,
+  answered and refused exactly like a gesture's. One call is one change.
+
+## How a record renders
+
+A confirmed record renders from the engine's appearance raster (`baked`)
+unless this session edited or created it, in which case it renders live from
+its description (`vector`): the `vector` preference in the state. Another
+session's change hands the record back to the raster (`sync/confirmed.ts`).
+While a change of this session is pending, how the record is drawn follows
+from the change itself (core `drawnAfter`, the engine's verdict on it): a move
+carries the raster along, anything else visible draws live, and a change the
+raster already shows (a flag) leaves it as it is. Stamps and widgets have no
+live rendering and always use a raster: a stamp's keeps its proportions in a
+resized box (the engine fits it `contain`), and a stamp this session placed
+shows the preview it was placed with until the engine's picture of it exists
+(`read/render.ts`). The raster is fetched again exactly when the record's
+appearance version changes, which the mirror advances when the engine reports
+a re-baked appearance.
+
+## Where things live
+
+| Folder          | What is in it                                                                         |
+| --------------- | ------------------------------------------------------------------------------------- |
+| `controller.ts` | the composition root: builds the services, wires every area, assembles the capability |
+| `model.ts`      | the plugin state and its transitions (`withSession`, render preferences, …)           |
+| `services/`     | what every area is built on: the store, object numbers, events, authority             |
+| `sync/`         | the records mirror (what the engine confirmed, and its prediction) and what follows   |
+| `read/`         | the view, and the reads the capability exposes (annotations, render items, chrome)    |
+| `write/`        | the verbs, and the op builders that turn core effects into the engine's ops           |
+| `comments/`     | the comment threads lens over the same records                                        |
+| `tools/`        | tool definitions, the registry, the tool's ghost, and the pointer handlers on the hub |
+
+## Tests
+
+`test/harness.ts` runs the controller on the kernel's test context with a
+fake engine that behaves like the real ones: it applies one change at a time,
+in the order they were sent, all or nothing, and publishes its events before
+it answers; a create gets the object number it names. `test/pending.test.ts`
+is the place to start: what the user sees while, and after, a change is on
+its way. `test/interleavings.test.ts` plays seeded random sequences of
+changes, refusals and remote updates, and checks the view (values and how
+the record renders) after every step.

package/dist/authoring.cjs

@@ -1,5 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_seam = require("./seam-6pJeKOOJ.cjs");
 let _embedpdf_core_annotation = require("@embedpdf/core-annotation");
 Object.defineProperty(exports, "MIN_DRAG", {
 	enumerable: true,
@@ -7,10 +6,21 @@ Object.defineProperty(exports, "MIN_DRAG", {
 		return _embedpdf_core_annotation.MIN_DRAG;
 	}
 });
+Object.defineProperty(exports, "gesturePlacement", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_core_annotation.gesturePlacement;
+	}
+});
 Object.defineProperty(exports, "resolveClickPlacement", {
 	enumerable: true,
 	get: function() {
 		return _embedpdf_core_annotation.resolveClickPlacement;
 	}
 });
-exports.widgetAppearanceFromProps = require_seam.widgetAppearanceFromProps;
+Object.defineProperty(exports, "widgetAppearanceOf", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_core_annotation.widgetAppearanceOf;
+	}
+});

package/dist/authoring.d.cts

@@ -1,2 +1,2 @@
-import { l as widgetAppearanceFromProps, n as MIN_DRAG, r as resolveClickPlacement, t as ClickPlacement } from "./authoring-BhtyfsMx.cjs";
-export { type ClickPlacement, MIN_DRAG, resolveClickPlacement, widgetAppearanceFromProps };
+import { MIN_DRAG, Placement, gesturePlacement, resolveClickPlacement, widgetAppearanceOf } from "@embedpdf/core-annotation";
+export { MIN_DRAG, type Placement, gesturePlacement, resolveClickPlacement, widgetAppearanceOf };

package/dist/authoring.d.ts

@@ -1,2 +1,2 @@
-import { l as widgetAppearanceFromProps, n as MIN_DRAG, r as resolveClickPlacement, t as ClickPlacement } from "./authoring-R4ezdnXd.js";
-export { type ClickPlacement, MIN_DRAG, resolveClickPlacement, widgetAppearanceFromProps };
+import { MIN_DRAG, Placement, gesturePlacement, resolveClickPlacement, widgetAppearanceOf } from "@embedpdf/core-annotation";
+export { MIN_DRAG, type Placement, gesturePlacement, resolveClickPlacement, widgetAppearanceOf };

package/dist/authoring.js

@@ -1,3 +1,2 @@
-import { h as widgetAppearanceFromProps } from "./seam-C4L_7rDt.js";
-import { MIN_DRAG, resolveClickPlacement } from "@embedpdf/core-annotation";
-export { MIN_DRAG, resolveClickPlacement, widgetAppearanceFromProps };
+import { MIN_DRAG, gesturePlacement, resolveClickPlacement, widgetAppearanceOf } from "@embedpdf/core-annotation";
+export { MIN_DRAG, gesturePlacement, resolveClickPlacement, widgetAppearanceOf };

package/dist/contract/host.cjs

@@ -1,3 +1,19 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_types = require("../types-Dlhdw2k_.cjs");
-exports.AnnotationToken = require_types.AnnotationToken;
+const require_contract = require("../contract-CPzpRG3h.cjs");
+const require_host_contract = require("../host-contract-DY9jFPPF.cjs");
+let _embedpdf_engine_core_public = require("@embedpdf/engine-core/public");
+exports.ANNOTATION_DEFAULTS = require_contract.ANNOTATION_DEFAULTS;
+exports.ANNOTATION_DRAW_PRIORITY = require_host_contract.ANNOTATION_DRAW_PRIORITY;
+exports.ANNOTATION_EDIT_PRIORITY = require_host_contract.ANNOTATION_EDIT_PRIORITY;
+exports.ANNOTATION_MARQUEE_PRIORITY = require_host_contract.ANNOTATION_MARQUEE_PRIORITY;
+exports.ANNOTATION_PLACE_PRIORITY = require_host_contract.ANNOTATION_PLACE_PRIORITY;
+exports.ARMED_STAMP_TOOL_ID = require_contract.ARMED_STAMP_TOOL_ID;
+exports.AnnotationToken = require_host_contract.AnnotationToken;
+Object.defineProperty(exports, "AnnotationTransfer", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_engine_core_public.AnnotationTransfer;
+	}
+});
+exports.annotationState = require_contract.annotationState;
+exports.previewBucket = require_host_contract.previewBucket;

package/dist/contract/host.d.cts

@@ -1,2 +1,3 @@
-import { _ as RecalibrationReport, i as AnnotationHostCapability, l as CapturedAnnotationDraft, s as AnnotationToken } from "../types-ChRnKozg.cjs";
-export { type AnnotationHostCapability, AnnotationToken, type CapturedAnnotationDraft, type RecalibrationReport };
+import { $ as Color, A as AnnotationResources, At as annotationState, B as AnnotationTool, C as AnnotationPatch, Ct as StampPlacement, D as AnnotationRef, Dt as ThreadDeleteResult, E as AnnotationProperty, Et as TextItem, F as AnnotationSelectionChangedEvent, G as ArmedStampInfo, Gt as Face, H as AnnotationTransfer, I as AnnotationSettings, J as AttachmentFileSource, K as ArmedStampPreview, Kt as TextFormat, L as AnnotationStampsApi, M as AnnotationRotationAnchor, Mt as ARMED_STAMP_TOOL_ID, N as AnnotationSelectionAnchor, O as AnnotationReorderedEvent, Ot as ToolDefaults, P as AnnotationSelectionApi, Q as ClickCreate, R as AnnotationSubtype, S as AnnotationOption, St as StampInput, T as AnnotationProperties, Tt as TextAlign, U as AnnotationUpdatedEvent, V as AnnotationToolsApi, W as AnnotationWriteFailedEvent, X as BlendMode, Y as Behavior, Z as ChromeSettings, _ as AnnotationHoverChangedEvent, _t as MarkupSubtype, a as AnnotationBundle, at as EditableKind, b as AnnotationImportResult, bt as ReviewStatus, c as AnnotationCreatedEvent, ct as FilePickerProvider, d as AnnotationDraftApi, dt as HandleRole, et as CommentThread, f as AnnotationDraftChangedEvent, ft as ImageGhost, g as AnnotationFlags, gt as LinkNavItem, h as AnnotationFilter, ht as LineStyle, i as AnnotationAnchor, it as CreationDraft, j as AnnotationResyncedEvent, k as AnnotationResourceRole, kt as ToolDefaultsChangedEvent, l as AnnotationDeletedEvent, lt as FilePromptRequest, m as AnnotationExportSelection, mt as LineEndings, n as AfterCreateSettings, nt as CommentThreadReview, o as AnnotationCapability, ot as EditableKinds, p as AnnotationEditingChangedEvent, pt as LineEnding, q as AttachmentContent, qt as TextSelection, r as Annotation, rt as CommentsApi, s as AnnotationConfig, st as FieldValues, t as ANNOTATION_DEFAULTS, tt as CommentThreadChangedEvent, u as AnnotationDraft, ut as FlagKey, v as AnnotationImportDrop, vt as MeasurementIntent, w as AnnotationPosition, wt as StampPreviewProvider, x as AnnotationLinksApi, xt as SnapSettings, y as AnnotationImportOptions, yt as PdfLinkTarget, z as AnnotationTextApi } from "../contract-BK4LHe9v.cjs";
+import { a as CapturedAnnotationDraft, c as ANNOTATION_DRAW_PRIORITY, d as ANNOTATION_PLACE_PRIORITY, f as AnnotationState, i as AnnotationToken, l as ANNOTATION_EDIT_PRIORITY, n as AnnotationHostCapability, o as RecalibrationReport, r as AnnotationLender, s as previewBucket, t as AnnotationAppearancePicture, u as ANNOTATION_MARQUEE_PRIORITY } from "../host-contract-BU29qDEw.cjs";
+export { ANNOTATION_DEFAULTS, ANNOTATION_DRAW_PRIORITY, ANNOTATION_EDIT_PRIORITY, ANNOTATION_MARQUEE_PRIORITY, ANNOTATION_PLACE_PRIORITY, ARMED_STAMP_TOOL_ID, AfterCreateSettings, type Annotation, AnnotationAnchor, AnnotationAppearancePicture, type AnnotationBundle, AnnotationCapability, AnnotationConfig, AnnotationCreatedEvent, AnnotationDeletedEvent, type AnnotationDraft, AnnotationDraftApi, AnnotationDraftChangedEvent, AnnotationEditingChangedEvent, AnnotationExportSelection, AnnotationFilter, type AnnotationFlags, AnnotationHostCapability, AnnotationHoverChangedEvent, type AnnotationImportDrop, type AnnotationImportOptions, AnnotationImportResult, AnnotationLender, AnnotationLinksApi, type AnnotationOption, type AnnotationPatch, type AnnotationPosition, AnnotationProperties, type AnnotationProperty, type AnnotationRef, AnnotationReorderedEvent, type AnnotationResourceRole, type AnnotationResources, AnnotationResyncedEvent, AnnotationRotationAnchor, AnnotationSelectionAnchor, AnnotationSelectionApi, AnnotationSelectionChangedEvent, AnnotationSettings, AnnotationStampsApi, type AnnotationState, type AnnotationSubtype, AnnotationTextApi, AnnotationToken, AnnotationTool, AnnotationToolsApi, AnnotationTransfer, AnnotationUpdatedEvent, AnnotationWriteFailedEvent, ArmedStampInfo, ArmedStampPreview, type AttachmentContent, type AttachmentFileSource, Behavior, type BlendMode, CapturedAnnotationDraft, ChromeSettings, type ClickCreate, type Color, type CommentThread, CommentThreadChangedEvent, type CommentThreadReview, CommentsApi, CreationDraft, type EditableKind, type EditableKinds, type Face, type FieldValues, FilePickerProvider, FilePromptRequest, type FlagKey, type HandleRole, ImageGhost, type LineEnding, type LineEndings, LineStyle, LinkNavItem, MarkupSubtype, type MeasurementIntent, type PdfLinkTarget, RecalibrationReport, type ReviewStatus, type SnapSettings, StampInput, StampPlacement, StampPreviewProvider, type TextAlign, type TextFormat, TextItem, type TextSelection, ThreadDeleteResult, ToolDefaults, ToolDefaultsChangedEvent, annotationState, previewBucket };

package/dist/contract/host.d.ts

@@ -1,2 +1,3 @@
-import { _ as RecalibrationReport, i as AnnotationHostCapability, l as CapturedAnnotationDraft, s as AnnotationToken } from "../types-Dmz3eRSG.js";
-export { type AnnotationHostCapability, AnnotationToken, type CapturedAnnotationDraft, type RecalibrationReport };
+import { $ as Color, A as AnnotationResources, At as annotationState, B as AnnotationTool, C as AnnotationPatch, Ct as StampPlacement, D as AnnotationRef, Dt as ThreadDeleteResult, E as AnnotationProperty, Et as TextItem, F as AnnotationSelectionChangedEvent, G as ArmedStampInfo, Gt as Face, H as AnnotationTransfer, I as AnnotationSettings, J as AttachmentFileSource, K as ArmedStampPreview, Kt as TextFormat, L as AnnotationStampsApi, M as AnnotationRotationAnchor, Mt as ARMED_STAMP_TOOL_ID, N as AnnotationSelectionAnchor, O as AnnotationReorderedEvent, Ot as ToolDefaults, P as AnnotationSelectionApi, Q as ClickCreate, R as AnnotationSubtype, S as AnnotationOption, St as StampInput, T as AnnotationProperties, Tt as TextAlign, U as AnnotationUpdatedEvent, V as AnnotationToolsApi, W as AnnotationWriteFailedEvent, X as BlendMode, Y as Behavior, Z as ChromeSettings, _ as AnnotationHoverChangedEvent, _t as MarkupSubtype, a as AnnotationBundle, at as EditableKind, b as AnnotationImportResult, bt as ReviewStatus, c as AnnotationCreatedEvent, ct as FilePickerProvider, d as AnnotationDraftApi, dt as HandleRole, et as CommentThread, f as AnnotationDraftChangedEvent, ft as ImageGhost, g as AnnotationFlags, gt as LinkNavItem, h as AnnotationFilter, ht as LineStyle, i as AnnotationAnchor, it as CreationDraft, j as AnnotationResyncedEvent, k as AnnotationResourceRole, kt as ToolDefaultsChangedEvent, l as AnnotationDeletedEvent, lt as FilePromptRequest, m as AnnotationExportSelection, mt as LineEndings, n as AfterCreateSettings, nt as CommentThreadReview, o as AnnotationCapability, ot as EditableKinds, p as AnnotationEditingChangedEvent, pt as LineEnding, q as AttachmentContent, qt as TextSelection, r as Annotation, rt as CommentsApi, s as AnnotationConfig, st as FieldValues, t as ANNOTATION_DEFAULTS, tt as CommentThreadChangedEvent, u as AnnotationDraft, ut as FlagKey, v as AnnotationImportDrop, vt as MeasurementIntent, w as AnnotationPosition, wt as StampPreviewProvider, x as AnnotationLinksApi, xt as SnapSettings, y as AnnotationImportOptions, yt as PdfLinkTarget, z as AnnotationTextApi } from "../contract-BOo9iZKo.js";
+import { a as CapturedAnnotationDraft, c as ANNOTATION_DRAW_PRIORITY, d as ANNOTATION_PLACE_PRIORITY, f as AnnotationState, i as AnnotationToken, l as ANNOTATION_EDIT_PRIORITY, n as AnnotationHostCapability, o as RecalibrationReport, r as AnnotationLender, s as previewBucket, t as AnnotationAppearancePicture, u as ANNOTATION_MARQUEE_PRIORITY } from "../host-contract-DfSvbt8c.js";
+export { ANNOTATION_DEFAULTS, ANNOTATION_DRAW_PRIORITY, ANNOTATION_EDIT_PRIORITY, ANNOTATION_MARQUEE_PRIORITY, ANNOTATION_PLACE_PRIORITY, ARMED_STAMP_TOOL_ID, AfterCreateSettings, type Annotation, AnnotationAnchor, AnnotationAppearancePicture, type AnnotationBundle, AnnotationCapability, AnnotationConfig, AnnotationCreatedEvent, AnnotationDeletedEvent, type AnnotationDraft, AnnotationDraftApi, AnnotationDraftChangedEvent, AnnotationEditingChangedEvent, AnnotationExportSelection, AnnotationFilter, type AnnotationFlags, AnnotationHostCapability, AnnotationHoverChangedEvent, type AnnotationImportDrop, type AnnotationImportOptions, AnnotationImportResult, AnnotationLender, AnnotationLinksApi, type AnnotationOption, type AnnotationPatch, type AnnotationPosition, AnnotationProperties, type AnnotationProperty, type AnnotationRef, AnnotationReorderedEvent, type AnnotationResourceRole, type AnnotationResources, AnnotationResyncedEvent, AnnotationRotationAnchor, AnnotationSelectionAnchor, AnnotationSelectionApi, AnnotationSelectionChangedEvent, AnnotationSettings, AnnotationStampsApi, type AnnotationState, type AnnotationSubtype, AnnotationTextApi, AnnotationToken, AnnotationTool, AnnotationToolsApi, AnnotationTransfer, AnnotationUpdatedEvent, AnnotationWriteFailedEvent, ArmedStampInfo, ArmedStampPreview, type AttachmentContent, type AttachmentFileSource, Behavior, type BlendMode, CapturedAnnotationDraft, ChromeSettings, type ClickCreate, type Color, type CommentThread, CommentThreadChangedEvent, type CommentThreadReview, CommentsApi, CreationDraft, type EditableKind, type EditableKinds, type Face, type FieldValues, FilePickerProvider, FilePromptRequest, type FlagKey, type HandleRole, ImageGhost, type LineEnding, type LineEndings, LineStyle, LinkNavItem, MarkupSubtype, type MeasurementIntent, type PdfLinkTarget, RecalibrationReport, type ReviewStatus, type SnapSettings, StampInput, StampPlacement, StampPreviewProvider, type TextAlign, type TextFormat, TextItem, type TextSelection, ThreadDeleteResult, ToolDefaults, ToolDefaultsChangedEvent, annotationState, previewBucket };

package/dist/contract/host.js

@@ -1,2 +1,3 @@
-import { t as AnnotationToken } from "../types-BvB1vUKb.js";
-export { AnnotationToken };
+import { n as AnnotationTransfer, r as ARMED_STAMP_TOOL_ID, s as annotationState, t as ANNOTATION_DEFAULTS } from "../contract-b2e_LZvu.js";
+import { a as ANNOTATION_MARQUEE_PRIORITY, i as ANNOTATION_EDIT_PRIORITY, n as previewBucket, o as ANNOTATION_PLACE_PRIORITY, r as ANNOTATION_DRAW_PRIORITY, t as AnnotationToken } from "../host-contract-CxrQPcPj.js";
+export { ANNOTATION_DEFAULTS, ANNOTATION_DRAW_PRIORITY, ANNOTATION_EDIT_PRIORITY, ANNOTATION_MARQUEE_PRIORITY, ANNOTATION_PLACE_PRIORITY, ARMED_STAMP_TOOL_ID, AnnotationToken, AnnotationTransfer, annotationState, previewBucket };