@embedpdf/vue 0.0.0-stage → 3.0.0-next.16

package/dist/annotation/AnnotationScene.vue.d.cts

@@ -0,0 +1,7 @@
+import type { RenderItem } from '@embedpdf/core-annotation';
+type __VLS_Props = {
+    item: RenderItem;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/AnnotationScene.vue.d.ts

@@ -0,0 +1,7 @@
+import type { RenderItem } from '@embedpdf/core-annotation';
+type __VLS_Props = {
+    item: RenderItem;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/FreeTextBox.vue.d.cts

@@ -0,0 +1,9 @@
+import type { TextItem } from '@embedpdf/plugin-annotation';
+import type { PageContextValue } from '../runtime/page.cjs';
+type __VLS_Props = {
+    item: TextItem;
+    page: PageContextValue;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/FreeTextBox.vue.d.ts

@@ -0,0 +1,9 @@
+import type { TextItem } from '@embedpdf/plugin-annotation';
+import type { PageContextValue } from '../runtime/page.js';
+type __VLS_Props = {
+    item: TextItem;
+    page: PageContextValue;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/NativeDrawing.vue.d.cts

@@ -0,0 +1,10 @@
+import { type RenderItem } from '@embedpdf/core-annotation';
+import { type AppearanceUrl } from '@embedpdf/web';
+type __VLS_Props = {
+    item: RenderItem;
+    /** The page's loaded pictures, by item and state; `null` until the first ones arrive. */
+    urls: Readonly<Record<string, AppearanceUrl>> | null;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/NativeDrawing.vue.d.ts

@@ -0,0 +1,10 @@
+import { type RenderItem } from '@embedpdf/core-annotation';
+import { type AppearanceUrl } from '@embedpdf/web';
+type __VLS_Props = {
+    item: RenderItem;
+    /** The page's loaded pictures, by item and state; `null` until the first ones arrive. */
+    urls: Readonly<Record<string, AppearanceUrl>> | null;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/StampGhost.vue.d.cts

@@ -0,0 +1,7 @@
+import type { PageContextValue } from '../runtime/page.cjs';
+type __VLS_Props = {
+    page: PageContextValue;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/StampGhost.vue.d.ts

@@ -0,0 +1,7 @@
+import type { PageContextValue } from '../runtime/page.js';
+type __VLS_Props = {
+    page: PageContextValue;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/annotation/composables.d.cts

@@ -0,0 +1,76 @@
+import type { MaybeRef, MaybeRefOrGetter, Ref } from 'vue';
+import type { EventHook } from '@embedpdf/core';
+import type { Annotation, AnnotationAnchor, AnnotationCapability, AnnotationFilter, AnnotationProperties, AnnotationRef, CommentsApi, FilePickerProvider, ToolDefaults } from '@embedpdf/plugin-annotation';
+import type { CommentThreadView } from './types.cjs';
+/**
+ * The annotation API (`create`, `update`, `selection`, `tools`, `text`,
+ * `comments`, …) for your chrome. The object never changes, so it's safe to
+ * keep in a closure; keep it whole (`annotation.selection.delete()`), since a
+ * member taken out of it once stays the one of that moment.
+ */
+export declare function useAnnotation(): AnnotationCapability;
+/** Subscribe to one annotation event while the component lives: `useAnnotationEvent((annotation) => annotation.onCreated, handler)`. */
+export declare function useAnnotationEvent<Event>(select: (annotation: AnnotationCapability) => EventHook<Event>, handler: (event: Event) => void): void;
+/**
+ * The annotations matching `filter` (some pages, one kind), in drawing order,
+ * as the user sees them, as a ref: the same array while they stay the same.
+ * A getter follows a filter that changes. Empty without a document.
+ */
+export declare function useAnnotationList(filter?: MaybeRefOrGetter<AnnotationFilter | undefined>): Readonly<Ref<readonly Annotation[]>>;
+/**
+ * A tool's defaults, as a ref: the fields its next annotation starts with,
+ * over the engine's. It follows them, so a color picker always shows the
+ * current color. Empty without a document.
+ */
+export declare function useAnnotationDefaults(toolId: MaybeRefOrGetter<string>): Readonly<Ref<ToolDefaults>>;
+/**
+ * What a style panel shows, as a ref: the selection's properties
+ * (`selection.getProperties()`), or, given a tool id, the tool's
+ * (`tools.getProperties(id)`). It follows them. Empty without a document.
+ */
+export declare function useAnnotationProperties(toolId?: MaybeRefOrGetter<string | undefined>): Readonly<Ref<AnnotationProperties>>;
+/**
+ * An anchor for `<Anchored>` that keeps a card or a badge attached to one
+ * annotation, as a ref: its page and the box around what it shows, following
+ * a move as it happens. `null` for `null`, or an annotation that isn't here.
+ * It changes when the annotation moves, not while people scroll or zoom: a
+ * note that keeps its size on screen hands `<Anchored>` its `boundsIn`. A
+ * getter follows a ref that changes (`() => hovered.value?.ref ?? null`).
+ */
+export declare function useAnnotationAnchor(ref: MaybeRefOrGetter<AnnotationRef | null>): Readonly<Ref<AnnotationAnchor | null>>;
+/**
+ * The comments API: the `comments` part of `useAnnotation()`, for the
+ * document in scope. Like `useAnnotation()`, the object never changes and
+ * always reaches the current document. Pair it with {@link useCommentThreads}
+ * for the threads to show.
+ */
+export declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document as a ref, display-ordered (page
+ * position, then top of page, then creation date) and with where its page is
+ * shown (`pageIndex`, `pageLabel`). It follows annotation writes (your own,
+ * remote ones, loading) and page moves and deletes; the same array between
+ * changes.
+ */
+export declare function useCommentThreads(): Readonly<Ref<readonly CommentThreadView[]>>;
+/**
+ * The thread holding any of its annotations (the root, a reply, a grouped
+ * part, a review state), as a ref, or null. A getter follows a ref that changes.
+ */
+export declare function useCommentThread(ref: MaybeRefOrGetter<AnnotationRef | null>): Readonly<Ref<CommentThreadView | null>>;
+/**
+ * The default file-picker provider: the browser's file dialog (from
+ * `@embedpdf/web`), honouring the tool's `accept` filter. The adapter fulfils
+ * the plugin's DOM-free port; the dialog never lives in the plugin.
+ */
+export declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the document in scope while the
+ * component lives: the one port behind every click-then-pick tool (a stamp
+ * whose source is `'prompt'`, the file attachment tool). Call it once, at a
+ * document-wide spot (not in a page layer). Without an argument it installs
+ * {@link filePickerProvider}, so those tools work out of the box; pass your
+ * own (an asset library, a cloud drive: switch on `toolId` or `subtype`), or
+ * `null` to make them do nothing. A ref follows a provider that changes.
+ */
+export declare function useFilePickerProvider(provider?: MaybeRef<FilePickerProvider | null>): void;

package/dist/annotation/composables.d.ts

@@ -0,0 +1,76 @@
+import type { MaybeRef, MaybeRefOrGetter, Ref } from 'vue';
+import type { EventHook } from '@embedpdf/core';
+import type { Annotation, AnnotationAnchor, AnnotationCapability, AnnotationFilter, AnnotationProperties, AnnotationRef, CommentsApi, FilePickerProvider, ToolDefaults } from '@embedpdf/plugin-annotation';
+import type { CommentThreadView } from './types.js';
+/**
+ * The annotation API (`create`, `update`, `selection`, `tools`, `text`,
+ * `comments`, …) for your chrome. The object never changes, so it's safe to
+ * keep in a closure; keep it whole (`annotation.selection.delete()`), since a
+ * member taken out of it once stays the one of that moment.
+ */
+export declare function useAnnotation(): AnnotationCapability;
+/** Subscribe to one annotation event while the component lives: `useAnnotationEvent((annotation) => annotation.onCreated, handler)`. */
+export declare function useAnnotationEvent<Event>(select: (annotation: AnnotationCapability) => EventHook<Event>, handler: (event: Event) => void): void;
+/**
+ * The annotations matching `filter` (some pages, one kind), in drawing order,
+ * as the user sees them, as a ref: the same array while they stay the same.
+ * A getter follows a filter that changes. Empty without a document.
+ */
+export declare function useAnnotationList(filter?: MaybeRefOrGetter<AnnotationFilter | undefined>): Readonly<Ref<readonly Annotation[]>>;
+/**
+ * A tool's defaults, as a ref: the fields its next annotation starts with,
+ * over the engine's. It follows them, so a color picker always shows the
+ * current color. Empty without a document.
+ */
+export declare function useAnnotationDefaults(toolId: MaybeRefOrGetter<string>): Readonly<Ref<ToolDefaults>>;
+/**
+ * What a style panel shows, as a ref: the selection's properties
+ * (`selection.getProperties()`), or, given a tool id, the tool's
+ * (`tools.getProperties(id)`). It follows them. Empty without a document.
+ */
+export declare function useAnnotationProperties(toolId?: MaybeRefOrGetter<string | undefined>): Readonly<Ref<AnnotationProperties>>;
+/**
+ * An anchor for `<Anchored>` that keeps a card or a badge attached to one
+ * annotation, as a ref: its page and the box around what it shows, following
+ * a move as it happens. `null` for `null`, or an annotation that isn't here.
+ * It changes when the annotation moves, not while people scroll or zoom: a
+ * note that keeps its size on screen hands `<Anchored>` its `boundsIn`. A
+ * getter follows a ref that changes (`() => hovered.value?.ref ?? null`).
+ */
+export declare function useAnnotationAnchor(ref: MaybeRefOrGetter<AnnotationRef | null>): Readonly<Ref<AnnotationAnchor | null>>;
+/**
+ * The comments API: the `comments` part of `useAnnotation()`, for the
+ * document in scope. Like `useAnnotation()`, the object never changes and
+ * always reaches the current document. Pair it with {@link useCommentThreads}
+ * for the threads to show.
+ */
+export declare function useComments(): CommentsApi;
+/**
+ * Every comment thread in the document as a ref, display-ordered (page
+ * position, then top of page, then creation date) and with where its page is
+ * shown (`pageIndex`, `pageLabel`). It follows annotation writes (your own,
+ * remote ones, loading) and page moves and deletes; the same array between
+ * changes.
+ */
+export declare function useCommentThreads(): Readonly<Ref<readonly CommentThreadView[]>>;
+/**
+ * The thread holding any of its annotations (the root, a reply, a grouped
+ * part, a review state), as a ref, or null. A getter follows a ref that changes.
+ */
+export declare function useCommentThread(ref: MaybeRefOrGetter<AnnotationRef | null>): Readonly<Ref<CommentThreadView | null>>;
+/**
+ * The default file-picker provider: the browser's file dialog (from
+ * `@embedpdf/web`), honouring the tool's `accept` filter. The adapter fulfils
+ * the plugin's DOM-free port; the dialog never lives in the plugin.
+ */
+export declare const filePickerProvider: FilePickerProvider;
+/**
+ * Install the file-picker provider for the document in scope while the
+ * component lives: the one port behind every click-then-pick tool (a stamp
+ * whose source is `'prompt'`, the file attachment tool). Call it once, at a
+ * document-wide spot (not in a page layer). Without an argument it installs
+ * {@link filePickerProvider}, so those tools work out of the box; pass your
+ * own (an asset library, a cloud drive: switch on `toolId` or `subtype`), or
+ * `null` to make them do nothing. A ref follows a provider that changes.
+ */
+export declare function useFilePickerProvider(provider?: MaybeRef<FilePickerProvider | null>): void;

package/dist/annotation/state.d.cts

@@ -0,0 +1,19 @@
+/**
+ * The annotation state as refs: `status` (`'loading'` until every annotation
+ * is in, then `'ready'`), the `selected` annotations, the one `hovered` under
+ * the pointer and the text box being typed in (`editing`). With a selector,
+ * one ref that updates only when the value it picks changes. Empty without a
+ * document.
+ */
+export declare const useAnnotationState: import("../index.cjs").StateComposable<{
+    status: import("@embedpdf/core").ResourceStatus;
+    selected: readonly import("@embedpdf/plugin-annotation").Annotation[];
+    hovered: import("@embedpdf/plugin-annotation").Annotation | null;
+    editing: import("@embedpdf/plugin-annotation").Annotation | null;
+}>;
+/**
+ * The annotation settings (`snap`, `chrome`, `afterCreate`, `tools`) as refs,
+ * or one ref for the value `select` picks. They belong to the plugin, so they
+ * read without a document; change them with `useAnnotation().updateSettings()`.
+ */
+export declare const useAnnotationSettings: import("../index.cjs").SettingsComposable<import("@embedpdf/plugin-annotation").AnnotationSettings & object>;

package/dist/annotation/state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The annotation state as refs: `status` (`'loading'` until every annotation
+ * is in, then `'ready'`), the `selected` annotations, the one `hovered` under
+ * the pointer and the text box being typed in (`editing`). With a selector,
+ * one ref that updates only when the value it picks changes. Empty without a
+ * document.
+ */
+export declare const useAnnotationState: import("../index.js").StateComposable<{
+    status: import("@embedpdf/core").ResourceStatus;
+    selected: readonly import("@embedpdf/plugin-annotation").Annotation[];
+    hovered: import("@embedpdf/plugin-annotation").Annotation | null;
+    editing: import("@embedpdf/plugin-annotation").Annotation | null;
+}>;
+/**
+ * The annotation settings (`snap`, `chrome`, `afterCreate`, `tools`) as refs,
+ * or one ref for the value `select` picks. They belong to the plugin, so they
+ * read without a document; change them with `useAnnotation().updateSettings()`.
+ */
+export declare const useAnnotationSettings: import("../index.js").SettingsComposable<import("@embedpdf/plugin-annotation").AnnotationSettings & object>;

package/dist/annotation/text-box.d.cts

@@ -0,0 +1,28 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import type { Annotation, TextItem } from '@embedpdf/plugin-annotation';
+import type { RichTextEditor } from './types.cjs';
+/**
+ * Make an element the editor of a text box, following `item` and `scale`
+ * (pixels per point). Returns the element's ref: put it on the element, and
+ * render nothing inside it, since the editor owns its children.
+ */
+export declare function useTextBoxEditor(item: MaybeRefOrGetter<TextItem | null>, scale: MaybeRefOrGetter<number>): Ref<HTMLElement | null>;
+/** Installed by the layer around a look it scales, not by app code. */
+export declare function provideLookScale(scale: Readonly<Ref<number>>): void;
+/**
+ * Make your own element the editor of a text box you draw yourself (a
+ * renderer for free text): it draws the runs, turns typing back into runs,
+ * keeps the caret when the style changes, and handles pasting, input methods
+ * and the format shortcuts. The formatting calls (`text.toggleFormat`,
+ * `selection.update`) work on it as they do on the built-in one.
+ *
+ * ```vue
+ * const { ref: editorRef, editing, style } = useRichTextEditor(() => props.annotation);
+ * <div :ref="editorRef" :class="{ editing }" :style="style" />
+ * ```
+ *
+ * `ref` goes on your element (render nothing inside it: the editor owns what's
+ * in it); `style` and `editing` are refs. `style` fills the element's parent at
+ * a legible size: draw the box's frame on the parent.
+ */
+export declare function useRichTextEditor(annotation: MaybeRefOrGetter<Annotation>): RichTextEditor;

package/dist/annotation/text-box.d.ts

@@ -0,0 +1,28 @@
+import type { MaybeRefOrGetter, Ref } from 'vue';
+import type { Annotation, TextItem } from '@embedpdf/plugin-annotation';
+import type { RichTextEditor } from './types.js';
+/**
+ * Make an element the editor of a text box, following `item` and `scale`
+ * (pixels per point). Returns the element's ref: put it on the element, and
+ * render nothing inside it, since the editor owns its children.
+ */
+export declare function useTextBoxEditor(item: MaybeRefOrGetter<TextItem | null>, scale: MaybeRefOrGetter<number>): Ref<HTMLElement | null>;
+/** Installed by the layer around a look it scales, not by app code. */
+export declare function provideLookScale(scale: Readonly<Ref<number>>): void;
+/**
+ * Make your own element the editor of a text box you draw yourself (a
+ * renderer for free text): it draws the runs, turns typing back into runs,
+ * keeps the caret when the style changes, and handles pasting, input methods
+ * and the format shortcuts. The formatting calls (`text.toggleFormat`,
+ * `selection.update`) work on it as they do on the built-in one.
+ *
+ * ```vue
+ * const { ref: editorRef, editing, style } = useRichTextEditor(() => props.annotation);
+ * <div :ref="editorRef" :class="{ editing }" :style="style" />
+ * ```
+ *
+ * `ref` goes on your element (render nothing inside it: the editor owns what's
+ * in it); `style` and `editing` are refs. `style` fills the element's parent at
+ * a legible size: draw the box's frame on the parent.
+ */
+export declare function useRichTextEditor(annotation: MaybeRefOrGetter<Annotation>): RichTextEditor;

package/dist/annotation/types.d.cts

@@ -0,0 +1,154 @@
+/**
+ * The types an app writes against when it draws annotations its own way:
+ * a renderer (which annotations, with which component), the props that
+ * component gets, what the `#handle` and `#rotation-handle` slots get, and
+ * what `useRichTextEditor()` and `useCommentThreads()` return.
+ */
+import type { Component, ComponentPublicInstance, CSSProperties, Ref } from 'vue';
+import type { Point, RenderItem } from '@embedpdf/core-annotation';
+import type { Annotation, CommentThread, HandleRole } from '@embedpdf/plugin-annotation';
+import type { PageContextValue } from '../runtime/page.cjs';
+/** The box a renderer draws into: the size to draw at, how it's turned, and how it's scaled. */
+export interface AnnotationFrame {
+    /** Its width in pixels at the annotation's 100% size, before its turn: draw at this. */
+    width: number;
+    /** Its height in pixels at the annotation's 100% size, before its turn: draw at this. */
+    height: number;
+    /**
+     * How it's turned on screen, degrees clockwise: the page's turn and the
+     * annotation's own. 0 is upright; turn your content by `-rotation` to keep
+     * it upright.
+     */
+    rotation: number;
+    /**
+     * How much the layer scales what you draw, with the page: the zoom, or for
+     * an annotation that keeps its size on screen, the zoom up to 1.
+     */
+    scale: number;
+}
+/**
+ * What a renderer's component gets as props: the annotation, the frame to
+ * draw into, and the layer's own drawing of it to keep or wrap. The layer
+ * keeps handling the pointer (select, move, resize) unless the renderer is
+ * `interactive`.
+ */
+export interface AnnotationRendererProps {
+    /** The annotation, as `get()` returns it. */
+    annotation: Annotation;
+    /**
+     * The box you draw into. The layer places, turns and scales it like the
+     * annotation's own drawing, also during a drag, a resize or a turn. Fill it
+     * (`width: 100%; height: 100%`) and draw at the annotation's 100% size: your
+     * text and borders scale with the page.
+     */
+    frame: AnnotationFrame;
+    /**
+     * The layer's own drawing of it, filling the frame: `<component :is="native" />`
+     * keeps the original look, to add to it.
+     */
+    native: Component;
+    /** The engine's picture of the annotation as an image (`url`), or `null`. `native` draws it in place. */
+    appearance: {
+        url: string;
+    } | null;
+    /** True while the pointer is over it. */
+    hovered: boolean;
+    /** True while it's selected. */
+    selected: boolean;
+    /** True when what you draw takes the pointer (see `interactive` on the renderer). */
+    interactive: boolean;
+}
+/**
+ * What a sibling plugin's renderer gets for the annotations its behavior owns
+ * (the form plugin's fill controls). It places its own controls: `item` is the
+ * layer's projection of the annotation (its box, style, text and raster box,
+ * in page coordinates), and `page.transform.toPixels()` turns those into the
+ * layer's pixels.
+ */
+export interface BehaviorRendererProps {
+    annotation: Annotation;
+    item: RenderItem;
+    page: PageContextValue;
+    /** The layer's own drawing of it, in its frame where the layer draws it: `<component :is="native" />`. */
+    native: Component;
+    hovered: boolean;
+    selected: boolean;
+    interactive: boolean;
+}
+/** What an `interactive` function is asked: the annotation, and the active tool. */
+export interface AnnotationInteractiveContext {
+    annotation: Annotation;
+    toolId: string;
+}
+/**
+ * One rule: "draw these annotations with this component". `for` gets the
+ * annotation with all its fields; the first renderer that matches wins.
+ * Without `interactive` the component only draws: the layer keeps handling
+ * the pointer. With `interactive` (or a function asked whenever it matters)
+ * the component takes the pointer, and the annotation can't be selected or
+ * moved while it does.
+ *
+ * Define the list once, in `<script setup>`: the layer registers each entry,
+ * and a list written inline in the template is a new one on every render.
+ *
+ * `{ behavior, component }` draws what a sibling plugin's behavior owns (the
+ * form plugin's fill controls); the plugin decides when it's engaged.
+ */
+export type AnnotationRenderer = {
+    behavior: string;
+    /** Gets {@link BehaviorRendererProps}. */
+    component: Component;
+} | {
+    /** A stable id for the registration (optional; generated). */
+    id?: string;
+    for: (annotation: Annotation) => boolean;
+    /** Gets {@link AnnotationRendererProps}. */
+    component: Component;
+    interactive?: boolean | ((context: AnnotationInteractiveContext) => boolean);
+    /**
+     * Scale what you draw with the page (the default): you draw at the
+     * annotation's 100% size. `false`: you draw at its size on screen, and
+     * size things yourself from `frame.scale`.
+     */
+    scale?: boolean;
+};
+/** What the layer's `#handle` slot gets: one handle to draw. */
+export interface HandleProps {
+    /** The handle's center, in pixels on the page. */
+    at: Point;
+    /** The `size` from the settings, px. */
+    size: number;
+    /** The selection's rotation (degrees clockwise), so a square handle can turn with it. */
+    rotation: number;
+    /** A box's `'corner'` or `'side'`, or one `'point'` of a line or a polygon. */
+    kind: HandleRole;
+    /** True while it's being dragged. */
+    active: boolean;
+}
+/** What the layer's `#rotation-handle` slot gets: a handle's props, and where its stalk starts on the box. */
+export interface RotationHandleProps extends Omit<HandleProps, 'kind'> {
+    /** Where the stalk starts on the box, in pixels on the page. */
+    from: Point;
+}
+/** What `useRichTextEditor()` gives the element you draw a text box with. */
+export interface RichTextEditor {
+    /** Put it on your element (`:ref="editor.ref"`): it becomes the editor. */
+    ref: (element: Element | ComponentPublicInstance | null) => void;
+    /** The box's body style as CSS: font, size, color and alignment. While typing it takes the pointer too. */
+    style: Readonly<Ref<CSSProperties>>;
+    /** True while someone types in the box. */
+    editing: Readonly<Ref<boolean>>;
+}
+/**
+ * A {@link CommentThread} with where its page is shown now. Identity stays
+ * `page` (like every annotation surface); these two fields are presentation,
+ * following page moves and deletes.
+ */
+export interface CommentThreadView extends CommentThread {
+    /** Current 0-based display index of the thread's page; `-1` when the page
+     *  is no longer in the document (for the one render before it goes). */
+    pageIndex: number;
+    /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+     *  else the 1-based position as a string: print it as it is. */
+    pageLabel: string;
+}

package/dist/annotation/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The types an app writes against when it draws annotations its own way:
+ * a renderer (which annotations, with which component), the props that
+ * component gets, what the `#handle` and `#rotation-handle` slots get, and
+ * what `useRichTextEditor()` and `useCommentThreads()` return.
+ */
+import type { Component, ComponentPublicInstance, CSSProperties, Ref } from 'vue';
+import type { Point, RenderItem } from '@embedpdf/core-annotation';
+import type { Annotation, CommentThread, HandleRole } from '@embedpdf/plugin-annotation';
+import type { PageContextValue } from '../runtime/page.js';
+/** The box a renderer draws into: the size to draw at, how it's turned, and how it's scaled. */
+export interface AnnotationFrame {
+    /** Its width in pixels at the annotation's 100% size, before its turn: draw at this. */
+    width: number;
+    /** Its height in pixels at the annotation's 100% size, before its turn: draw at this. */
+    height: number;
+    /**
+     * How it's turned on screen, degrees clockwise: the page's turn and the
+     * annotation's own. 0 is upright; turn your content by `-rotation` to keep
+     * it upright.
+     */
+    rotation: number;
+    /**
+     * How much the layer scales what you draw, with the page: the zoom, or for
+     * an annotation that keeps its size on screen, the zoom up to 1.
+     */
+    scale: number;
+}
+/**
+ * What a renderer's component gets as props: the annotation, the frame to
+ * draw into, and the layer's own drawing of it to keep or wrap. The layer
+ * keeps handling the pointer (select, move, resize) unless the renderer is
+ * `interactive`.
+ */
+export interface AnnotationRendererProps {
+    /** The annotation, as `get()` returns it. */
+    annotation: Annotation;
+    /**
+     * The box you draw into. The layer places, turns and scales it like the
+     * annotation's own drawing, also during a drag, a resize or a turn. Fill it
+     * (`width: 100%; height: 100%`) and draw at the annotation's 100% size: your
+     * text and borders scale with the page.
+     */
+    frame: AnnotationFrame;
+    /**
+     * The layer's own drawing of it, filling the frame: `<component :is="native" />`
+     * keeps the original look, to add to it.
+     */
+    native: Component;
+    /** The engine's picture of the annotation as an image (`url`), or `null`. `native` draws it in place. */
+    appearance: {
+        url: string;
+    } | null;
+    /** True while the pointer is over it. */
+    hovered: boolean;
+    /** True while it's selected. */
+    selected: boolean;
+    /** True when what you draw takes the pointer (see `interactive` on the renderer). */
+    interactive: boolean;
+}
+/**
+ * What a sibling plugin's renderer gets for the annotations its behavior owns
+ * (the form plugin's fill controls). It places its own controls: `item` is the
+ * layer's projection of the annotation (its box, style, text and raster box,
+ * in page coordinates), and `page.transform.toPixels()` turns those into the
+ * layer's pixels.
+ */
+export interface BehaviorRendererProps {
+    annotation: Annotation;
+    item: RenderItem;
+    page: PageContextValue;
+    /** The layer's own drawing of it, in its frame where the layer draws it: `<component :is="native" />`. */
+    native: Component;
+    hovered: boolean;
+    selected: boolean;
+    interactive: boolean;
+}
+/** What an `interactive` function is asked: the annotation, and the active tool. */
+export interface AnnotationInteractiveContext {
+    annotation: Annotation;
+    toolId: string;
+}
+/**
+ * One rule: "draw these annotations with this component". `for` gets the
+ * annotation with all its fields; the first renderer that matches wins.
+ * Without `interactive` the component only draws: the layer keeps handling
+ * the pointer. With `interactive` (or a function asked whenever it matters)
+ * the component takes the pointer, and the annotation can't be selected or
+ * moved while it does.
+ *
+ * Define the list once, in `<script setup>`: the layer registers each entry,
+ * and a list written inline in the template is a new one on every render.
+ *
+ * `{ behavior, component }` draws what a sibling plugin's behavior owns (the
+ * form plugin's fill controls); the plugin decides when it's engaged.
+ */
+export type AnnotationRenderer = {
+    behavior: string;
+    /** Gets {@link BehaviorRendererProps}. */
+    component: Component;
+} | {
+    /** A stable id for the registration (optional; generated). */
+    id?: string;
+    for: (annotation: Annotation) => boolean;
+    /** Gets {@link AnnotationRendererProps}. */
+    component: Component;
+    interactive?: boolean | ((context: AnnotationInteractiveContext) => boolean);
+    /**
+     * Scale what you draw with the page (the default): you draw at the
+     * annotation's 100% size. `false`: you draw at its size on screen, and
+     * size things yourself from `frame.scale`.
+     */
+    scale?: boolean;
+};
+/** What the layer's `#handle` slot gets: one handle to draw. */
+export interface HandleProps {
+    /** The handle's center, in pixels on the page. */
+    at: Point;
+    /** The `size` from the settings, px. */
+    size: number;
+    /** The selection's rotation (degrees clockwise), so a square handle can turn with it. */
+    rotation: number;
+    /** A box's `'corner'` or `'side'`, or one `'point'` of a line or a polygon. */
+    kind: HandleRole;
+    /** True while it's being dragged. */
+    active: boolean;
+}
+/** What the layer's `#rotation-handle` slot gets: a handle's props, and where its stalk starts on the box. */
+export interface RotationHandleProps extends Omit<HandleProps, 'kind'> {
+    /** Where the stalk starts on the box, in pixels on the page. */
+    from: Point;
+}
+/** What `useRichTextEditor()` gives the element you draw a text box with. */
+export interface RichTextEditor {
+    /** Put it on your element (`:ref="editor.ref"`): it becomes the editor. */
+    ref: (element: Element | ComponentPublicInstance | null) => void;
+    /** The box's body style as CSS: font, size, color and alignment. While typing it takes the pointer too. */
+    style: Readonly<Ref<CSSProperties>>;
+    /** True while someone types in the box. */
+    editing: Readonly<Ref<boolean>>;
+}
+/**
+ * A {@link CommentThread} with where its page is shown now. Identity stays
+ * `page` (like every annotation surface); these two fields are presentation,
+ * following page moves and deletes.
+ */
+export interface CommentThreadView extends CommentThread {
+    /** Current 0-based display index of the thread's page; `-1` when the page
+     *  is no longer in the document (for the one render before it goes). */
+    pageIndex: number;
+    /** The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+     *  else the 1-based position as a string: print it as it is. */
+    pageLabel: string;
+}