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

package/LICENSE

@@ -0,0 +1,192 @@
+Copyright 2026 CloudPDF LTD
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use files in this distribution except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-----------------------------------------------------------------------
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# @embedpdf/vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Vue 3 adapter for EmbedPDF: components for your templates and composables for
+`<script setup>`. One import path per feature (`@embedpdf/vue/stage`, `@embedpdf/vue/render`), so
+a feature you don't use never reaches your bundle.
+
+```vue
+<script setup lang="ts">
+import { DocumentGate, Viewer } from '@embedpdf/vue/runtime';
+import { Stage, stagePlugin } from '@embedpdf/vue/stage';
+import { RenderLayer, renderPlugin } from '@embedpdf/vue/render';
+import { localEngine } from '@embedpdf/engine';
+
+const engine = localEngine();
+const plugins = [stagePlugin(), renderPlugin()];
+</script>
+
+<template>
+  <Viewer :engine="engine" :plugins="plugins" :initial-documents="[{ source: { kind: 'url', url: '/file.pdf' } }]">
+    <DocumentGate>
+      <template #fallback><p>Opening…</p></template>
+      <Stage style="height: 600px">
+        <template #page><RenderLayer /></template>
+      </Stage>
+    </DocumentGate>
+  </Viewer>
+</template>
+```
+
+The documentation is at [embedpdf.com/docs/headless/vue](https://www.embedpdf.com/docs/headless/vue).
+
+## How the package is written
+
+**Components are single-file components (`.vue`), composables are plain TypeScript.** A component
+here is mostly a template with slots and `v-model`, which is what a Vue developer reads and writes
+every day; `defineProps`, `defineEmits`, `defineSlots` and `defineModel` give typed props, events
+and scoped slots to the app's templates through `vue-tsc`. Render functions in `defineComponent`
+would hide that template behind `h()` calls. The cost is a build step that understands `.vue`
+(Vite with `@vitejs/plugin-vue`, and `vue-tsc` for the declarations), which every Vue app has.
+
+Each feature is an entry file and a folder: `src/stage.ts` is `@embedpdf/vue/stage`, and its
+components and composables live in `src/stage/`. The entry re-exports the plugin
+(`export * from '@embedpdf/plugin-stage'`), so `stagePlugin()` comes from the same import as
+`<Stage>`.
+
+| Script                                  | What it does                                                                                                             |
+| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `pnpm --filter @embedpdf/vue test`      | Vitest in happy-dom, with `@vue/test-utils`                                                                              |
+| `pnpm --filter @embedpdf/vue typecheck` | `vue-tsc` over `src` and `test`, with `strictTemplates`                                                                  |
+| `pnpm --filter @embedpdf/vue build`     | Vite library build (ESM and CJS, one file per entry) into `dist`, `vue-tsc` declarations, then the publish check (below) |
+
+In the workspace, `exports` points at the source, so tests, the docs' checks and the demos read
+it directly. `publishConfig.exports` points the published package at `dist` (`import` and
+`require`, each with its declarations next to it, as in the React package). The build reads its
+entries from `exports`, and `test/package-exports.test.ts` checks the two lists agree.
+
+Nothing in the workspace reads `dist`, so the build ends by proving it.
+`tooling/build/src/fully-specify-imports.mjs` gives every relative import in `dist` its file
+(`./stage/scope.js`, which Node, webpack and TypeScript's `node16` need), and writes the `.d.cts`
+declarations a `require` reads. `tooling/build/src/check-framework-package.mjs` then packs the
+package, runs publint and attw on the tarball, and type-checks the app in `consumer/` against it
+with `vue-tsc`: the lines in `consumer/Canary.vue` marked `error expected` must fail, and nothing
+else may. A failure there is what a user would get from npm.
+
+## How the binding works
+
+- **`<Viewer>` owns the kernel.** It creates and starts it when it mounts (never on the server),
+  destroys it when it unmounts, and provides one binding: the kernel, and `track()`, which makes a
+  computed depend on the kernel's one change stream.
+- **Every reader is a computed.** `useKernelValue(select, isEqual)` runs `select` on every kernel
+  change and on a change to any ref it reads, and keeps its value while `isEqual` says nothing
+  changed, so a template updates only when what it shows did. Everything below is built on it.
+- **A plugin's API is a live object.** A component's setup runs once, so `useCapability(token)`
+  returns an object whose members are read from the capability the subtree resolves to now: the
+  document in scope, or a stand-in while there is none (`standInFor` from `@embedpdf/core`:
+  reading never throws, calling refuses with `not-ready`, the settings calls work). A method that
+  returns a promise (`form.setValue`, `redaction.markPage`) then rejects, so `.catch()` sees it;
+  the others throw. It never changes, so it is safe in closures and handlers.
+- **The read rule, the same in every adapter.** A method named `get*`, `list*`, `is*`, `has*` or
+  `can*` (the capability vocabulary's reads, `docs/conventions/naming.md`) is a read: called in a
+  template, a `computed` or a `watchEffect`, it updates when its answer changes
+  (`v-if="annotation.canCreate()"`). Every other method tracks nothing, so a `watchEffect` that
+  calls `stage.reveal(index)` runs again only when `index` changes. Never destructure the API
+  object (`const { update } = useMetadata()`): keep it, and call through it.
+- **State is refs.** Without a selector, a state composable returns one ref per field
+  (`const { zoomLevel } = useStageState()`), so destructuring keeps them reactive and a template
+  reads them unwrapped. With a selector, it returns one ref. A composable that returns one value
+  returns a ref (`usePageList()`, `usePage()`).
+- **An argument that can change is a `MaybeRefOrGetter`**: `useStage(() => props.token)`,
+  `useToolCursor(() => ({ … }))`.
+- **Events end with the component.** `useCapabilityEvent(token, select, handler)` subscribes to
+  the document in scope, again when that document changes, and stops on unmount.
+- **The page context is the seam.** A page surface provides it (`providePage`), and a layer reads
+  it with `usePage()`, a ref whose value changes when the page's geometry does (a zoom, a turn),
+  never on a pan.
+- **Scopes are provide/inject.** `<DocumentScope :id>` picks the document, `<StageScope :token>`
+  (and `<Stage>` for its own pages and overlay) the stage lens.
+- **Anything that touches the DOM generically** (the stage's gestures, painted images, the
+  anchored placement math, cursors, the theme variables) comes from `@embedpdf/web`, shared with
+  the other adapters. So does what every page surface computes: the page context
+  (`makePageContext`), the surface's boxes (`pageSurfaceLayout`), the Stage's and a page view's
+  projectors, the page's pointer listener (`attachPagePointer`) and the scrollbar
+  (`scrollbarLayout`, `createScrollbarPresses`).
+
+## Adding a plugin binding
+
+The steps for a new feature, `search` as the example. React's binding
+(`packages/framework/react/src/search.tsx`) is the reference for behavior; the plugin's contract
+is the API.
+
+1. **The entry.** Create `src/search.ts`, and add both lines to `package.json`:
+   `"./search": "./src/search.ts"` in `exports`, and the `dist` pair in `publishConfig.exports`
+   (copy one; `test/package-exports.test.ts` fails until both exist). Start the entry with what it
+   is for, then re-export the plugin:
+
+   ```ts
+   /** @embedpdf/vue/search: … */
+   export * from '@embedpdf/plugin-search';
+   ```
+
+2. **The API**, a live object:
+
+   ```ts
+   export function useSearch(): SearchCapability {
+     return useCapability(SearchToken);
+   }
+   ```
+
+3. **The state and the settings**, one line each, from the plugin's `defineState` declaration and
+   its token. They return refs per field, or one ref with a selector:
+
+   ```ts
+   export const useSearchState = stateComposable(searchState);
+   export const useSearchSettings = settingsComposable(SearchToken);
+   ```
+
+4. **The events**, cleaned up on unmount:
+
+   ```ts
+   export function useSearchEvent<Event>(
+     select: (search: SearchCapability) => EventHook<Event>,
+     handler: (event: Event) => void,
+   ): void {
+     useCapabilityEvent(SearchToken, select, handler);
+   }
+   ```
+
+5. **A one-value reader is a ref**, built on `useOptionalSelector` (null-safe: `fallback` without
+   a document) or `useKernelValue`. **A reader with an argument takes a `MaybeRefOrGetter`** and
+   reads it with `toValue()` inside the select, so it follows the argument:
+
+   ```ts
+   export function useSearchHits(): Readonly<Ref<readonly SearchHit[]>> {
+     return useOptionalSelector(SearchToken, (search) => search.getHits(), NO_HITS);
+   }
+   export function useAnnotationAnchor(annotation: MaybeRefOrGetter<AnnotationRef | null>) {
+     return useOptionalSelector(AnnotationToken, (api) => anchorOf(api, toValue(annotation)), null);
+   }
+   ```
+
+6. **A component** is an SFC in `src/search/`, exported from the entry
+   (`export { default as SearchLayer } from './search/SearchLayer.vue'`). React's props map as the
+   docs' rules say (`docs/kit/mdx/frameworks.mjs`): a value prop is a prop (`color` →
+   `:color`), `onHitClick` is an event (`defineEmits<{ hitClick: [hit: SearchHit] }>()`, used as
+   `@hit-click`; when the component must know whether anyone listens, as `<SearchLayer>` does to
+   let matches take the pointer only then, declare it as an optional function prop `onHitClick`
+   instead: `@hit-click` still works and is typed), a controlled value is a model (`defineModel('page')`, used as `v-model:page`, or
+   a `page` prop with an `update:page` event when the component must tell its own changes from
+   yours, as `<Stage>` does), and a render prop is a scoped slot (`renderLink` →
+   `<template #link="{ link }">`, declared with `defineSlots`). Something the app hands you to
+   draw (a `native` renderer) is drawn with `<component :is>`. Write the TSDoc on each prop, event
+   and slot: it is what the app sees in its editor. `class` and `style` fall through to your root
+   element; a component with several roots has none.
+
+7. **A layer drawn on each page** reads the page with `usePage()` and its document through the
+   usual composables (inside a page there is always one). Read `page.value` inside a computed or a
+   selector, never once at setup, so it follows the page's geometry; place things in view space
+   with `page.value.transform` (`pageToViewRect`, `viewScale`), and remember Vue doesn't add
+   `px` to numbers in `:style`. Work with the DOM in a `watch` with `flush: 'post'` and clean up
+   with `onCleanup`. A layer that paints a part of the page itself (the annotations, the form
+   fields) says so with `usePaintsPagePart` (`src/page-layers.ts`), and `<RenderLayer>` leaves that
+   part out of the page's picture. `RenderLayer.vue` is the example to copy.
+
+8. **UI that floats over a page** goes in the Stage's `#overlay` slot and positions with
+   `<Anchored :anchor>`; a component of yours that needs the projection reads
+   `useProjectorBinding()`. A page surface of your own (a standalone page view) provides its page
+   with `providePage(computed(() => makePageContext(…)))`, its document with
+   `provideDocumentScope` (`src/runtime/kernel.ts`), and its projection by wrapping what floats in
+   `<AnchoredScope :binding :shown>`; `src/stage/PageSurface.vue` and `src/stage/Stage.vue` show
+   all three.
+
+9. **Missing shared logic.** Anything DOM-level comes from `@embedpdf/web`. If logic every adapter
+   needs is missing there, write the small piece you need next to your feature and list it as a
+   candidate for `@embedpdf/web`, rather than editing a shared package.
+
+10. **A test** in `test/search.test.ts`, the way React's binding test does it: mount through
+    `viewerWith(plugins, () => h(Probe))` from `test/counter-plugin.ts`, where `probe(setup)`
+    makes a component of a setup function; drive the kernel (`kernel.documents.open(…)`,
+    `kernel.capability(Token)`), `await settle()`, and assert on what rendered or what a ref holds.
+    Test the binding (refs update only when their value changes, events stop on unmount, the
+    component's slots and models), not the plugin.
+
+11. **Check**: `pnpm --filter @embedpdf/vue test`, `typecheck` and `build`; then the docs'
+    `pnpm --filter @embedpdf/docs-content snippets` (your pages compile for Vue) and
+    `samples <area>` (your examples compile).
+
+## What the foundation provides
+
+| Entry | Names |
+| :-- | :-- |
+| `runtime` | `Viewer` (`:engine`, `:plugins`, `:initial-documents`, `:identity`, `:scope`, `:accent`, `:page`, `@ready`, `#fallback`, `#error`), `DocumentGate` (`#fallback`, `#locked`, `#error`), `DocumentScope` (`:id`); `useDocuments`, `useDocument`, `useDocumentsState`, `useDocumentsEvent`, `usePageList`, `useViewerSettings`; `useKernel`, `useKernelValue`, `useCapability`, `useCapabilityRef`, `useOptionalCapability`, `useSelector`, `useOptionalSelector`, `useCapabilityEvent`, `useDocumentScope`, `useDocumentId`, `useActiveDocumentId`; `usePage`, `providePage`, `makePageContext`, `PageContextValue`; `fieldRefs`, `FieldRefs`; `saveFile`, `mountWebFont`, `epdfTheme`; everything from `@embedpdf/core` |
+| `stage` | `Stage` (`#page`, `#page-chrome`, `#overlay`, `v-model:page`, `v-model:zoom`, `v-model:tool`, `:token`), `StageScope`, `Scrollbar`; `useStage`, `useStageState`, `useStageSettings`, `useStageEvent`, `useScrollMetrics`, `useStageToken`; the stage plugin |
+| `render` | `RenderLayer` (`:annotations`, `:tiles`); `useRender`, `useRenderSettings`, `useRenderEvent`; the render plugin |
+| `interaction` | `PagePointerSource`; `useInteraction`, `useInteractionState`, `useInteractionSettings`, `useInteractionEvent`, `useToolCursor`, `createClickCounter`; `svgCursor`, `vibrationFeedback`, `wkFeedback`; the interaction plugin |
+| `anchored` | `Anchored` (`:anchor`, `placement`, `:gap`, `pinned`), `AnchoredScope`; `useProjectorBinding`, `useOptionalProjectorBinding`, `useShownPages`, `provideProjector`, `provideShownPages` |
+| `.` (`src/state.ts`) | `stateComposable`, `settingsComposable`, and every entry above |
+
+Added since by the feature agents (see each entry's source): `view-manager`, `page-edit`,
+`metadata`, `actions` (`useActionsUiAdapter(handlers)`, a `MaybeRefOrGetter`); `page-view`
+(`PageView` with `#fallback` and `#page-chrome`), `selection` (`SelectionLayer`,
+`SelectionMenu` and `SelectionHandles` in the Stage's `#overlay`, `SelectionClipboard`), `search`
+(`SearchLayer` with `@hit-click`, `useSearchHits(page?)`), `link` (`LinkLayer` with
+`#link="{ link, native }"`). Never destructure a plugin's API handle (`const { update } =
+useMetadata()`): setup runs once, so keep the handle and call through it.
+
+Your app's own UI: `commands` (`useCommand(id)` is a ref, `useCommandShortcuts({ target })`
+takes a template ref), `toolbar` (`Toolbar` with `#command`, `#custom="{ name, variant }"`,
+`#collapsed`, `#group-trigger`, `#separator`, `#overflow-trigger`, `#overflow-menu`; a slot that
+draws nothing for a part falls back to the default: `#custom` draws every custom item, and one it
+draws nothing for shows its command's button; without `#custom`, each custom item is a native
+`<slot>` socket), `shell` (`useSurface(id)` gives `isOpen` and
+`props` as refs, so destructure it), `i18n` (`useT()` reads the language reactively). A slot
+outlet can't pass a prop named `name` with `:name` (that names the outlet): bind an object,
+`v-bind="{ name, variant }"`.
+
+Annotations: `annotation` (`AnnotationLayer` with `:renderers` and the `#handle` /
+`#rotation-handle` slots; a renderer's component gets `AnnotationRendererProps` and draws
+`native` with `<component :is="native" />`; `AnnotationMenu`, `AnnotationDraftMenu`
+(`v-slot="{ draft }"`) and `AnnotationRotationBadge` (`v-slot="{ rotation }"`) go in the Stage's
+`#overlay`). `useAnnotationList(filter?)`, `useAnnotationDefaults(toolId)`,
+`useAnnotationProperties(toolId?)`, `useAnnotationAnchor(ref)`, `useCommentThreads()` and
+`useCommentThread(ref)` are refs and take getters; `useRichTextEditor(annotation)` gives `ref` (a
+function ref, for `:ref`), `style` and `editing` (refs); `useFilePickerProvider(provider?)` takes
+a provider or a ref, never a getter, because the provider is itself a function. Another entry
+that needs `useAnnotationState` or `useAnnotationSettings` without the layer imports
+`src/annotation/state.ts`.
+
+Marks: `stamp` (`useStampLibraries(filter?)`, `useStampAssets(filter?)` and
+`useStampAssetPreviewUrl(assetId)` are refs and take getters; the preview's object URL is revoked
+when it's no longer shown), `measurement` (`usePageScale(page)`, `useMeasurementReadout(ref)`),
+`redaction` (`usePendingRedactions(filter?)`). They have no components: an armed stamp, a
+measurement and a redaction mark are drawn by the annotation layer.
+
+Forms: `form` (`FormLayer` in the Stage's `#page`, above `RenderLayer` and `AnnotationLayer`;
+`useFormValue(ref)` is a ref and takes a getter), `signature` (`useSignerRows()` is a ref; the
+signers come with the plugin). Each control of `FormLayer` builds its box with `useWidgetBox`
+(`src/form/widget-box.ts`): a composable, so the toggle's box can be its control; the press is
+kept from the Stage with `isolatePointerDown`, and the widget's PDF events come from
+`bindWidgetEvents` on the same box.

package/dist/Anchored.vue_vue_type_script_setup_true_lang-BEImlFso.cjs

@@ -0,0 +1,124 @@
+"use strict";
+const vue = require("vue");
+const web = require("@embedpdf/web");
+const projector = require("./projector-Cf7879sx.cjs");
+const _sfc_main$1 = /* @__PURE__ */ vue.defineComponent({
+  __name: "PlacedAnchored",
+  props: {
+    target: {},
+    placement: {},
+    gap: {},
+    pinned: { type: Boolean }
+  },
+  setup(__props) {
+    const props = __props;
+    const binding = projector.useProjectorBinding();
+    const element = vue.ref(null);
+    const fit = vue.shallowRef(null);
+    const browserMoves = vue.ref(0);
+    const space = vue.computed(() => binding.value.projector.space);
+    vue.watch(
+      () => binding.value.subscribe,
+      (subscribe, _previous, onCleanup) => {
+        if (subscribe) onCleanup(subscribe(() => browserMoves.value += 1));
+      },
+      { immediate: true }
+    );
+    vue.onMounted(() => {
+      if (space.value === "client") browserMoves.value += 1;
+    });
+    vue.watch(
+      [() => binding.value.projector, () => props.target],
+      () => {
+        if (space.value === "client") browserMoves.value += 1;
+      },
+      { flush: "post" }
+    );
+    vue.watch(
+      [element, space],
+      ([content, viewSpace], _previous, onCleanup) => {
+        if (!content) return;
+        onCleanup(
+          web.observeAnchoredFit(content, viewSpace, (next) => {
+            if (!web.sameAnchoredFit(fit.value, next)) fit.value = next;
+          })
+        );
+      },
+      { immediate: true, flush: "post" }
+    );
+    const position = vue.computed(() => {
+      void browserMoves.value;
+      return web.projectAnchoredTarget(
+        binding.value.projector,
+        props.target,
+        { placement: props.placement, gap: props.gap, pinned: props.pinned },
+        fit.value
+      );
+    });
+    const style = vue.computed(() => {
+      const placed = position.value;
+      if (!placed) return null;
+      return {
+        position: space.value === "client" ? "fixed" : "absolute",
+        left: `${placed.left}px`,
+        top: `${placed.top}px`,
+        // Its own width, wherever it sits: the size the placement measured.
+        width: "max-content",
+        transform: placed.transform,
+        pointerEvents: "auto"
+      };
+    });
+    return (_ctx, _cache) => {
+      return vue.openBlock(), vue.createBlock(vue.Teleport, {
+        to: "body",
+        disabled: space.value !== "client"
+      }, [
+        style.value ? (vue.openBlock(), vue.createElementBlock("div", {
+          key: 0,
+          ref_key: "element",
+          ref: element,
+          style: vue.normalizeStyle(style.value),
+          onPointerdown: _cache[0] || (_cache[0] = vue.withModifiers(() => {
+          }, ["stop"]))
+        }, [
+          vue.renderSlot(_ctx.$slots, "default")
+        ], 36)) : vue.createCommentVNode("", true)
+      ], 8, ["disabled"]);
+    };
+  }
+});
+const _sfc_main = /* @__PURE__ */ vue.defineComponent({
+  __name: "Anchored",
+  props: {
+    anchor: {},
+    placement: { default: "top" },
+    gap: { default: 8 },
+    pinned: { type: Boolean, default: false }
+  },
+  setup(__props) {
+    const props = __props;
+    const shown = projector.useShownPages();
+    const target = vue.computed(() => {
+      const anchor = props.anchor;
+      if (!(anchor == null ? void 0 : anchor.bounds)) return null;
+      if (shown && !shown.value.has(anchor.page.objectNumber)) return null;
+      return { ...anchor, bounds: anchor.bounds };
+    });
+    return (_ctx, _cache) => {
+      return target.value ? (vue.openBlock(), vue.createBlock(_sfc_main$1, {
+        key: 0,
+        target: target.value,
+        placement: __props.placement,
+        gap: __props.gap,
+        pinned: __props.pinned
+      }, {
+        default: vue.withCtx(() => [
+          vue.renderSlot(_ctx.$slots, "default")
+        ]),
+        _: 3
+      }, 8, ["target", "placement", "gap", "pinned"])) : vue.createCommentVNode("", true);
+    };
+  }
+});
+exports._sfc_main = _sfc_main;
+//# sourceMappingURL=Anchored.vue_vue_type_script_setup_true_lang-BEImlFso.cjs.map

package/dist/Anchored.vue_vue_type_script_setup_true_lang-BEImlFso.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Anchored.vue_vue_type_script_setup_true_lang-BEImlFso.cjs","sources":["../src/anchored/PlacedAnchored.vue","../src/anchored/Anchored.vue"],"sourcesContent":["<!--\n  Anchored UI on a page that is shown: it follows the camera. The projection\n  runs during render from the shared pure helper; the content's size and the\n  view's are measured after mount and whenever either resizes (a camera move\n  changes neither). In client space (a surface without a camera) it is\n  teleported to the body and placed `fixed`, out of reach of any ancestor's\n  overflow clipping.\n-->\n<script setup lang=\"ts\">\nimport { computed, onMounted, ref, shallowRef, watch } from 'vue';\nimport type { CSSProperties } from 'vue';\nimport { observeAnchoredFit, projectAnchoredTarget, sameAnchoredFit } from '@embedpdf/web';\nimport type { AnchoredFit, AnchoredPlacement, AnchorTarget } from '@embedpdf/web';\nimport { useProjectorBinding } from './projector';\n\nconst props = defineProps<{\n  target: AnchorTarget;\n  placement: AnchoredPlacement;\n  gap: number;\n  pinned: boolean;\n}>();\n\ndefineSlots<{ default?(): unknown }>();\n\nconst binding = useProjectorBinding();\nconst element = ref<HTMLDivElement | null>(null);\nconst fit = shallowRef<AnchoredFit | null>(null);\n// Bumped by browser-driven invalidation, which no state change announces.\nconst browserMoves = ref(0);\n\nconst space = computed(() => binding.value.projector.space);\n\nwatch(\n  () => binding.value.subscribe,\n  (subscribe, _previous, onCleanup) => {\n    if (subscribe) onCleanup(subscribe(() => (browserMoves.value += 1)));\n  },\n  { immediate: true },\n);\n\n// A client-space surface measures the DOM, which doesn't exist during its\n// first render: one more pass after mount shows the position as soon as it\n// can be measured.\nonMounted(() => {\n  if (space.value === 'client') browserMoves.value += 1;\n});\nwatch(\n  [() => binding.value.projector, () => props.target],\n  () => {\n    if (space.value === 'client') browserMoves.value += 1;\n  },\n  { flush: 'post' },\n);\n\nwatch(\n  [element, space],\n  ([content, viewSpace], _previous, onCleanup) => {\n    if (!content) return;\n    onCleanup(\n      observeAnchoredFit(content, viewSpace, (next) => {\n        if (!sameAnchoredFit(fit.value, next)) fit.value = next;\n      }),\n    );\n  },\n  { immediate: true, flush: 'post' },\n);\n\nconst position = computed(() => {\n  void browserMoves.value;\n  return projectAnchoredTarget(\n    binding.value.projector,\n    props.target,\n    { placement: props.placement, gap: props.gap, pinned: props.pinned },\n    fit.value,\n  );\n});\n\nconst style = computed((): CSSProperties | null => {\n  const placed = position.value;\n  if (!placed) return null;\n  return {\n    position: space.value === 'client' ? 'fixed' : 'absolute',\n    left: `${placed.left}px`,\n    top: `${placed.top}px`,\n    // Its own width, wherever it sits: the size the placement measured.\n    width: 'max-content',\n    transform: placed.transform,\n    pointerEvents: 'auto',\n  };\n});\n</script>\n\n<template>\n  <Teleport to=\"body\" :disabled=\"space !== 'client'\">\n    <div v-if=\"style\" ref=\"element\" :style=\"style\" @pointerdown.stop>\n      <slot />\n    </div>\n  </Teleport>\n</template>\n","<!--\n  <Anchored>: positions its content around a page-space box, on whichever page\n  surface is in scope (a <Stage>'s #overlay slot). Once its size is measured it\n  flips to the other side when the chosen one has no room, and stays inside the\n  view, unless `pinned`. A click inside it never reaches the surface (which\n  would read it as a click outside). On a page that isn't shown it renders\n  nothing and reads only the pages on screen, so hundreds of badges cost only\n  the ones in view while people scroll and zoom.\n-->\n<script setup lang=\"ts\">\nimport { computed } from 'vue';\nimport type { AnchoredPlacement, AnchoredRect, AnchorTarget } from '@embedpdf/web';\nimport PlacedAnchored from './PlacedAnchored.vue';\nimport { useShownPages } from './projector';\n\nconst props = withDefaults(\n  defineProps<{\n    /**\n     * The box on a page to sit next to, in page coordinates: `{ page, bounds }`,\n     * with `avoid` points to keep clear of. `null`, or a target without\n     * `bounds` (a search match with no geometry), hides it.\n     */\n    anchor: (Omit<AnchorTarget, 'bounds'> & { bounds?: AnchoredRect }) | null;\n    /** Where to sit: a side of the box, centred, or lined up with the side's start or end (`'top-end'`). */\n    placement?: AnchoredPlacement;\n    /**\n     * Gap in screen px between the box and the content, and between the content\n     * and the view's edge. Negative overlaps the box.\n     */\n    gap?: number;\n    /**\n     * Stay where `placement` puts it: never flip to the other side, never move\n     * to stay in view, and scroll away with the box. For badges and status;\n     * menus leave it off.\n     */\n    pinned?: boolean;\n  }>(),\n  { placement: 'top', gap: 8, pinned: false },\n);\n\ndefineSlots<{ default?(): unknown }>();\n\nconst shown = useShownPages();\n\n/** The anchor with its box, while it has one on a shown page. */\nconst target = computed((): AnchorTarget | null => {\n  const anchor = props.anchor;\n  if (!anchor?.bounds) return null;\n  if (shown && !shown.value.has(anchor.page.objectNumber)) return null;\n  return { ...anchor, bounds: anchor.bounds };\n});\n</script>\n\n<template>\n  <PlacedAnchored v-if=\"target\" :target=\"target\" :placement=\"placement\" :gap=\"gap\" :pinned=\"pinned\">\n    <slot />\n  </PlacedAnchored>\n</template>\n"],"names":["useProjectorBinding","ref","shallowRef","computed","watch","onMounted","observeAnchoredFit","sameAnchoredFit","projectAnchoredTarget","_createBlock","_Teleport","_createElementBlock","_renderSlot","useShownPages","PlacedAnchored"],"mappings":"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"}