From 8ca065b083e3466cdaff482119dcba4d892a89fd Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:21 -0300
Subject: [PATCH 01/11] docs: improve project positioning and onboarding

---
 README.md | 170 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 144 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index c0df9e2..a66efa6 100644
--- a/README.md
+++ b/README.md
@@ -5,17 +5,118 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 # PDF Elements
 
-A Vue 3 component for rendering PDFs with draggable and resizable element overlays.
+[![npm version](https://img.shields.io/npm/v/@libresign/pdf-elements)](https://www.npmjs.com/package/@libresign/pdf-elements)
+[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](COPYING)
+[![Node CI](https://github.com/LibreSign/pdf-elements/actions/workflows/node.yml/badge.svg)](https://github.com/LibreSign/pdf-elements/actions/workflows/node.yml)
+[![Tests](https://github.com/LibreSign/pdf-elements/actions/workflows/tests.yml/badge.svg)](https://github.com/LibreSign/pdf-elements/actions/workflows/tests.yml)
 
-**[Demo](https://libresign.github.io/pdf-elements/)** · [Examples](examples/)
+A Vue 3 PDF viewer for building interactive document workflows with draggable, resizable and fully customizable overlay elements.
+
+Use it to build signature placement, form-field positioning, annotations, review tools, document preparation flows and other PDF experiences where users need to place or manipulate elements on top of a document.
+
+**[Try the live demo](https://libresign.github.io/pdf-elements/)** · **[Install from npm](https://www.npmjs.com/package/@libresign/pdf-elements)** · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
 
 ![The pdf-elements demo with a sample PDF loaded and a signature element placed on the first page](img/screenshot/demo.png)
 
+## Why PDF Elements?
+
+PDF rendering is only part of many document workflows. Applications often also need to let users place, move, resize, inspect or remove interactive elements over PDF pages.
+
+PDF Elements provides that UI layer as a reusable Vue 3 component.
+
+- **PDF.js-based rendering** for browser PDF viewing
+- **Draggable and resizable overlays** positioned directly on PDF pages
+- **Custom element types** rendered through Vue slots
+- **Interactive placement mode** for adding elements to a document
+- **Multiple PDF documents** in the same component
+- **Read-only mode** for review and presentation flows
+- **Custom action toolbars** for host-application controls
+- **Themeable UI** using CSS variables
+- **Typed public API** for TypeScript projects
+- **ES module package** published as `@libresign/pdf-elements`
+
+PDF Elements does **not** cryptographically sign or modify the PDF by itself. It focuses on the browser interaction layer, so you can connect it to your own signing, storage, form or document-processing backend.
+
+## Install
+
+```bash
+npm install @libresign/pdf-elements
+```
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import PDFElements from '@libresign/pdf-elements'
+
+const pdf = ref()
+const files = ref([
+  'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf',
+])
+
+function addSignatureField() {
+  pdf.value?.startAddingElement({
+    type: 'signature',
+    width: 160,
+    height: 48,
+    label: 'Signature',
+  })
+}
+</script>
+
+<template>
+  <button @click="addSignatureField">
+    Add signature field
+  </button>
+
+  <PDFElements
+    ref="pdf"
+    :init-files="files"
+    :init-file-names="['sample.pdf']"
+  >
+    <template #element-signature="{ object }">
+      <div>
+        {{ object.label }}
+      </div>
+    </template>
+  </PDFElements>
+</template>
+```
+
+For a more complete integration with custom controls, actions and document handling, see the [basic example](examples/basic/).
+
+## Use cases
+
+PDF Elements is suitable for applications that need a visual PDF interaction layer, including:
+
+- electronic-signature and document-preparation interfaces;
+- placing signature, initials, date or text placeholders;
+- PDF annotation and review tools;
+- document form builders;
+- approval and document workflow applications;
+- custom business applications that need coordinates and sizing for PDF overlays.
+
 ## Development
 
-- `npm run dev` - Run the demo with Vite
-- `npm run build` - Build the library (ESM + types)
-- `npm run build:demo` - Build the demo to `dist-demo`
+Requirements are defined in `package.json`.
+
+```bash
+npm ci
+npm run dev
+```
+
+Useful commands:
+
+| Command | Purpose |
+|---|---|
+| `npm run dev` | Run the interactive demo with Vite |
+| `npm run build` | Build the library |
+| `npm run build:demo` | Build the hosted demo to `dist-demo` |
+| `npm run lint` | Run ESLint |
+| `npm run typecheck` | Run the Vue/TypeScript type checker |
+| `npm test` | Run unit tests |
+| `npm run test:e2e` | Run Playwright end-to-end tests |
 
 ## API
 
@@ -44,20 +145,20 @@ A Vue 3 component for rendering PDFs with draggable and resizable element overla
 
 Example:
 
-```ts
+```vue
 <PDFElements
-	:pdfjs-options="{
-		disableFontFace: true,
-		disableRange: true,
-		disableStream: true,
-	}"
+  :pdfjs-options="{
+    disableFontFace: true,
+    disableRange: true,
+    disableStream: true,
+  }"
 />
 ```
 
 ### Events
 
-- `pdf-elements:end-init` - Emitted when PDF is loaded
-- `pdf-elements:adding-ended` - Emitted when interactive placement ends. Payload: `{ reason: 'placed', object, docIndex, pageIndex }` on success or `{ reason: 'cancelled' }` when the placement is cancelled.
+- `pdf-elements:end-init` - Emitted when PDF is loaded.
+- `pdf-elements:adding-ended` - Emitted when interactive placement ends. Payload: `{ reason: 'placed', object, docIndex, pageIndex }` on success or `{ reason: 'cancelled' }` when placement is cancelled.
 
 ### Exposed methods
 
@@ -66,9 +167,9 @@ Example:
 
 ### Slots
 
-- `element-{type}` - Custom element rendering (e.g., `element-signature`)
-- `custom` - Fallback for elements without specific type
-- `actions` - Custom action buttons
+- `element-{type}` - Custom element rendering, for example `element-signature`.
+- `custom` - Fallback for elements without a specific type slot.
+- `actions` - Custom action buttons.
 
 #### `actions` slot props
 
@@ -81,21 +182,21 @@ The `actions` slot receives:
 - `actionClass` (`pdf-elements-action-btn`)
 - `actionAttrs` (`{ 'data-pdf-elements-action': 'true' }`)
 
-Use these hooks to style third-party button components consistently (for example, Nextcloud `NcButton`) without relying on internal scoped selectors.
+These hooks allow host applications to style third-party button components consistently without depending on internal scoped selectors.
 
 Example:
 
 ```vue
 <template #actions="slotProps">
-	<NcButton
-		:class="slotProps.actionClass"
-		v-bind="slotProps.actionAttrs"
-		type="button"
-		variant="tertiary"
-		@click.stop="slotProps.onDuplicate"
-	>
-		Duplicate
-	</NcButton>
+  <NcButton
+    :class="slotProps.actionClass"
+    v-bind="slotProps.actionAttrs"
+    type="button"
+    variant="tertiary"
+    @click.stop="slotProps.onDuplicate"
+  >
+    Duplicate
+  </NcButton>
 </template>
 ```
 
@@ -121,3 +222,20 @@ Action toolbar and action buttons can be themed via CSS variables and follow hos
 | `--pdf-elements-action-btn-min-width` | Action button min width |
 | `--pdf-elements-action-btn-shadow` | Action button shadow |
 | `--pdf-elements-action-btn-hover-background` | Action button hover background |
+
+## Community
+
+Bug reports, feature ideas, documentation improvements, tests and code contributions are welcome.
+
+- Found a bug? [Open a bug report](https://github.com/LibreSign/pdf-elements/issues/new/choose).
+- Have an idea? [Start a feature request](https://github.com/LibreSign/pdf-elements/issues/new/choose).
+- Want to contribute code? Read [CONTRIBUTING.md](CONTRIBUTING.md).
+- Want to understand the project first? Try the [live demo](https://libresign.github.io/pdf-elements/) and inspect the [examples](examples/).
+
+Small, focused pull requests are welcome, including documentation, accessibility, testing and developer-experience improvements.
+
+## License
+
+PDF Elements is free software licensed under the [GNU AGPL-3.0-or-later](COPYING).
+
+The project is maintained by the LibreSign community and LibreCode.

From f895d33e5a756d4210700a0711bba291cc74d7f2 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:24 -0300
Subject: [PATCH 02/11] docs: improve contributor onboarding

---
 CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 91 insertions(+), 45 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3149c1c..9a60c70 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,67 +5,113 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 # Contributing to @libresign/pdf-elements
 
-Thank you for your interest in contributing to @libresign/pdf-elements! We welcome contributions from the community.
+Contributions are welcome. You do not need to work on a large feature to help: bug reports, reproduction cases, documentation, accessibility improvements, tests and focused code changes are all useful.
 
-## Code of Conduct
+## Before you start
+
+- Check the [open issues](https://github.com/LibreSign/pdf-elements/issues) to avoid duplicate work.
+- For a substantial behavior or API change, open an issue first so the approach can be discussed before implementation.
+- Keep pull requests focused on one problem whenever possible.
+
+## Reporting bugs
+
+Use the bug report template and include:
+
+- a clear description of the problem;
+- exact steps to reproduce it;
+- expected and actual behavior;
+- browser and operating-system information when relevant;
+- a minimal reproduction or sample PDF when possible;
+- screenshots or console output when they help explain the issue.
+
+Please avoid attaching confidential or sensitive documents.
+
+## Suggesting improvements
+
+Feature requests are welcome. Describe the user problem first, then the proposed solution. Concrete use cases make requests easier to evaluate and implement.
+
+Good contributions are not limited to new features. Improvements to documentation, test coverage, accessibility, performance and developer experience are also valuable.
+
+## Development setup
+
+1. Fork the repository.
+2. Clone your fork:
 
-This project follows the LibreSign Code of Conduct. By participating, you are expected to uphold this code.
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/pdf-elements.git
+   cd pdf-elements
+   ```
 
-## How to Contribute
+3. Install dependencies:
 
-### Reporting Bugs
+   ```bash
+   npm ci
+   ```
 
-Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+4. Start the demo:
 
-* Use a clear and descriptive title
-* Describe the exact steps which reproduce the problem
-* Provide specific examples to demonstrate the steps
-* Describe the behavior you observed after following the steps
-* Explain which behavior you expected to see instead and why
-* Include screenshots if possible
+   ```bash
+   npm run dev
+   ```
 
-### Suggesting Enhancements
+5. Create a focused branch and make your changes.
 
-Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
+## Validate your change
 
-* Use a clear and descriptive title
-* Provide a detailed description of the suggested enhancement
-* Provide examples of how the enhancement would be used
-* Explain why this enhancement would be useful
+Run the checks relevant to your change before opening a pull request:
 
-### Pull Requests
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+```
 
-* Fill in the required template
-* Follow the JavaScript/Vue.js style guide
-* Include SPDX headers in all new files
-* Update the README.md with details of changes if needed
-* Update the CHANGELOG.md following Keep a Changelog format
-* Ensure all tests pass and linting is clean
+For user-interface or browser behavior changes, also run:
 
-## Development Setup
+```bash
+npm run test:e2e
+```
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/pdf-elements.git`
-3. Install dependencies: `npm install`
-4. Create a feature branch: `git checkout -b my-feature`
-5. Make your changes
-6. Run lint: `npm run lint`
-7. Build the library: `npm run build:lib`
-8. Commit your changes: `git commit -am 'Add some feature'`
-9. Push to the branch: `git push origin my-feature`
-10. Create a Pull Request
+The CI executes linting, type checking, package validation, unit tests and Playwright coverage.
 
-## Coding Standards
+## Pull requests
 
-* Use 2 spaces for indentation
-* Follow Vue.js style guide
-* Add SPDX headers to all source files:
-  ```javascript
-  // SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
-  // SPDX-License-Identifier: AGPL-3.0-or-later
+A good pull request should:
+
+- explain the problem being solved;
+- describe the approach taken;
+- include regression coverage for bug fixes when practical;
+- update documentation when public behavior changes;
+- include SPDX headers in new source files;
+- keep unrelated refactors out of the same change.
+
+Use meaningful Conventional Commit-style messages where possible, for example:
+
+```
+fix: keep element coordinates after zoom
+feat: expose custom page footer slot
+docs: add worker configuration example
+test: cover cancelled element placement
+```
+
+## Coding standards
+
+- Follow the existing Vue and TypeScript conventions in the repository.
+- Use the repository ESLint configuration instead of manually formatting around lint rules.
+- Add SPDX headers to new source files:
+
+  ```text
+  SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+  SPDX-License-Identifier: AGPL-3.0-or-later
   ```
-* Write meaningful commit messages
-* Keep pull requests focused on a single feature or fix
+
+- Prefer small components and focused changes.
+- Add or update tests for behavior changes.
+
+## Code of Conduct
+
+This project follows the [LibreSign Code of Conduct](https://github.com/LibreSign/libresign/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to follow it.
 
 ## License
 

From dbd5668b4d2521bb137ec40d33f62a65fc4865ed Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:26 -0300
Subject: [PATCH 03/11] docs: improve package discoverability

---
 package.json | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/package.json b/package.json
index 83700f0..31ec5a8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@libresign/pdf-elements",
-  "description": "PDF viewer with draggable and resizable element overlays for Vue 3",
+  "description": "Vue 3 PDF viewer with draggable and resizable overlay elements for document workflows",
   "version": "1.2.7",
   "author": "LibreCode <contact@librecode.coop>",
   "private": false,
@@ -24,15 +24,21 @@
   "bugs": {
     "url": "https://github.com/LibreSign/pdf-elements/issues"
   },
-  "homepage": "https://github.com/LibreSign/pdf-elements#readme",
+  "homepage": "https://libresign.github.io/pdf-elements/",
   "keywords": [
     "pdf",
-    "viewer",
+    "pdfjs",
+    "pdf-viewer",
+    "pdf-editor",
+    "document-workflow",
+    "electronic-signature",
     "annotations",
+    "overlay",
     "draggable",
     "resizable",
-    "libresign",
-    "vue3"
+    "vue",
+    "vue3",
+    "libresign"
   ],
   "scripts": {
     "dev": "vite",

From af3a51c1f5679fc70262c4a47dae97e5c1eb4d67 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:51 -0300
Subject: [PATCH 04/11] docs: add structured bug report template

---
 .github/ISSUE_TEMPLATE/bug_report.yml | 70 +++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..e6fca03
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Bug report
+description: Report a reproducible problem in PDF Elements
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve PDF Elements. Please provide a minimal, reproducible report and do not upload confidential PDFs.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the problem and what you expected instead.
+      placeholder: Tell us what you observed and what should have happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include the smallest set of steps, code or sample needed to reproduce the issue.
+      placeholder: |
+        1. Render PDFElements with...
+        2. Add an element...
+        3. Resize...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: PDF Elements version
+      placeholder: e.g. 1.2.7
+    validations:
+      required: true
+
+  - type: input
+    id: vue
+    attributes:
+      label: Vue version
+      placeholder: e.g. 3.5.28
+
+  - type: input
+    id: environment
+    attributes:
+      label: Browser and operating system
+      placeholder: e.g. Firefox 143 on Fedora 42
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Console output or screenshots
+      description: Paste relevant logs or drag screenshots here. Remove secrets and sensitive data.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues for duplicates.
+          required: true
+        - label: I removed confidential or sensitive information from the report.
+          required: true

From 91939e4dfbc20139d96d840a57f12d6b4884f31d Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:53 -0300
Subject: [PATCH 05/11] docs: add feature request template

---
 .github/ISSUE_TEMPLATE/feature_request.yml | 51 ++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml

diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..94a3cbb
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Feature request
+description: Propose an improvement or new use case for PDF Elements
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the user or developer problem before describing the solution.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Show where this would be useful in a real PDF or document workflow.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe an API, UI or behavior if you already have an approach in mind.
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Include workarounds or alternative approaches you have tried.
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be interested in working on this change.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues for similar requests.
+          required: true

From d04411b0442d3d6d25af21c607033acba54bd24f Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:56 -0300
Subject: [PATCH 06/11] docs: add issue chooser links

---
 .github/ISSUE_TEMPLATE/config.yml | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..6523418
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+blank_issues_enabled: true
+contact_links:
+  - name: Live demo
+    url: https://libresign.github.io/pdf-elements/
+    about: Reproduce and explore PDF Elements behavior in the browser.
+  - name: LibreSign
+    url: https://github.com/LibreSign/libresign
+    about: Report issues that belong to the LibreSign application rather than the PDF Elements component.

From a4f64779a8f3b649a34a3e4ac9082312165e5a20 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 13:56:58 -0300
Subject: [PATCH 07/11] docs: add pull request template

---
 .github/pull_request_template.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 .github/pull_request_template.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..9f9d30f
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,20 @@
+<!--
+SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+## What does this change?
+
+Describe the problem and the approach used to solve it.
+
+## How was it tested?
+
+List the automated or manual checks you ran.
+
+## Checklist
+
+- [ ] The change is focused on one problem.
+- [ ] Tests were added or updated when behavior changed.
+- [ ] Documentation was updated when public behavior or APIs changed.
+- [ ] `npm run lint`, `npm run typecheck`, `npm run test` and `npm run build` pass when applicable.
+- [ ] New source files include SPDX headers.

From 1b4edc95133ff49032f6079f03ec2d5b88283656 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 14:02:16 -0300
Subject: [PATCH 08/11] docs: keep readme focused on project overview

---
 README.md | 167 +++++-------------------------------------------------
 1 file changed, 13 insertions(+), 154 deletions(-)

diff --git a/README.md b/README.md
index a66efa6..46dfc0d 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,6 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 # PDF Elements
 
 [![npm version](https://img.shields.io/npm/v/@libresign/pdf-elements)](https://www.npmjs.com/package/@libresign/pdf-elements)
-[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](COPYING)
 [![Node CI](https://github.com/LibreSign/pdf-elements/actions/workflows/node.yml/badge.svg)](https://github.com/LibreSign/pdf-elements/actions/workflows/node.yml)
 [![Tests](https://github.com/LibreSign/pdf-elements/actions/workflows/tests.yml/badge.svg)](https://github.com/LibreSign/pdf-elements/actions/workflows/tests.yml)
 
@@ -14,7 +13,7 @@ A Vue 3 PDF viewer for building interactive document workflows with draggable, r
 
 Use it to build signature placement, form-field positioning, annotations, review tools, document preparation flows and other PDF experiences where users need to place or manipulate elements on top of a document.
 
-**[Try the live demo](https://libresign.github.io/pdf-elements/)** · **[Install from npm](https://www.npmjs.com/package/@libresign/pdf-elements)** · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
+**[Try the live demo](https://libresign.github.io/pdf-elements/)** · **[Install from npm](https://www.npmjs.com/package/@libresign/pdf-elements)** · [Examples](examples/) · [API](docs/API.md) · [Contributing](CONTRIBUTING.md)
 
 ![The pdf-elements demo with a sample PDF loaded and a signature element placed on the first page](img/screenshot/demo.png)
 
@@ -22,7 +21,7 @@ Use it to build signature placement, form-field positioning, annotations, review
 
 PDF rendering is only part of many document workflows. Applications often also need to let users place, move, resize, inspect or remove interactive elements over PDF pages.
 
-PDF Elements provides that UI layer as a reusable Vue 3 component.
+PDF Elements provides that interaction layer as a reusable Vue 3 component.
 
 - **PDF.js-based rendering** for browser PDF viewing
 - **Draggable and resizable overlays** positioned directly on PDF pages
@@ -33,9 +32,8 @@ PDF Elements provides that UI layer as a reusable Vue 3 component.
 - **Custom action toolbars** for host-application controls
 - **Themeable UI** using CSS variables
 - **Typed public API** for TypeScript projects
-- **ES module package** published as `@libresign/pdf-elements`
 
-PDF Elements does **not** cryptographically sign or modify the PDF by itself. It focuses on the browser interaction layer, so you can connect it to your own signing, storage, form or document-processing backend.
+PDF Elements does **not** cryptographically sign or modify the PDF by itself. It focuses on the browser interaction layer, so it can be connected to signing, storage, form or document-processing backends.
 
 ## Install
 
@@ -76,166 +74,27 @@ function addSignatureField() {
     :init-file-names="['sample.pdf']"
   >
     <template #element-signature="{ object }">
-      <div>
-        {{ object.label }}
-      </div>
+      <div>{{ object.label }}</div>
     </template>
   </PDFElements>
 </template>
 ```
 
-For a more complete integration with custom controls, actions and document handling, see the [basic example](examples/basic/).
+For a fuller integration with custom controls, actions and document handling, see the [basic example](examples/basic/).
 
 ## Use cases
 
-PDF Elements is suitable for applications that need a visual PDF interaction layer, including:
+PDF Elements can be used for:
 
 - electronic-signature and document-preparation interfaces;
-- placing signature, initials, date or text placeholders;
+- signature, initials, date or text placement;
 - PDF annotation and review tools;
 - document form builders;
-- approval and document workflow applications;
-- custom business applications that need coordinates and sizing for PDF overlays.
+- approval and document workflows;
+- applications that need coordinates and sizing for PDF overlays.
 
-## Development
+## Documentation
 
-Requirements are defined in `package.json`.
-
-```bash
-npm ci
-npm run dev
-```
-
-Useful commands:
-
-| Command | Purpose |
-|---|---|
-| `npm run dev` | Run the interactive demo with Vite |
-| `npm run build` | Build the library |
-| `npm run build:demo` | Build the hosted demo to `dist-demo` |
-| `npm run lint` | Run ESLint |
-| `npm run typecheck` | Run the Vue/TypeScript type checker |
-| `npm test` | Run unit tests |
-| `npm run test:e2e` | Run Playwright end-to-end tests |
-
-## API
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `width` | String | `'100%'` | Container width |
-| `height` | String | `'100%'` | Container height |
-| `initFiles` | Array | `[]` | PDF files to load |
-| `initFileNames` | Array | `[]` | Names for the PDF files |
-| `initialScale` | Number | `1` | Initial zoom scale |
-| `showPageFooter` | Boolean | `true` | Show page footer with document name and page number |
-| `hideSelectionUI` | Boolean | `false` | Hide selection handles and actions UI |
-| `showSelectionHandles` | Boolean | `true` | Show resize/move handles on selected elements |
-| `showElementActions` | Boolean | `true` | Show action buttons on selected elements |
-| `readOnly` | Boolean | `false` | Disable drag, resize, and actions for elements |
-| `ignoreClickOutsideSelectors` | Array | `[]` | CSS selectors that keep the selection active when clicking outside the element |
-| `pageCountFormat` | String | `'{currentPage} of {totalPages}'` | Format string for page counter |
-| `autoFitZoom` | Boolean | `false` | Automatically adjust zoom to fit viewport on window resize |
-| `pdfjsOptions` | Object | `{}` | Options passed to PDF.js `getDocument` (advanced) |
-
-### PDF.js options
-
-`pdfjsOptions` is forwarded to PDF.js `getDocument(...)` and can be used to tune performance.
-
-Example:
-
-```vue
-<PDFElements
-  :pdfjs-options="{
-    disableFontFace: true,
-    disableRange: true,
-    disableStream: true,
-  }"
-/>
-```
-
-### Events
-
-- `pdf-elements:end-init` - Emitted when PDF is loaded.
-- `pdf-elements:adding-ended` - Emitted when interactive placement ends. Payload: `{ reason: 'placed', object, docIndex, pageIndex }` on success or `{ reason: 'cancelled' }` when placement is cancelled.
-
-### Exposed methods
-
-- `startAddingElement(templateObject)` - Starts interactive placement mode.
-- `cancelAdding()` - Cancels the current placement session and emits `pdf-elements:adding-ended` with `{ reason: 'cancelled' }` when a session was active.
-
-### Slots
-
-- `element-{type}` - Custom element rendering, for example `element-signature`.
-- `custom` - Fallback for elements without a specific type slot.
-- `actions` - Custom action buttons.
-
-#### `actions` slot props
-
-The `actions` slot receives:
-
-- `object`
-- `onDelete`
-- `onDuplicate`
-- `toolbarClass` (`pdf-elements-actions-toolbar`)
-- `actionClass` (`pdf-elements-action-btn`)
-- `actionAttrs` (`{ 'data-pdf-elements-action': 'true' }`)
-
-These hooks allow host applications to style third-party button components consistently without depending on internal scoped selectors.
-
-Example:
-
-```vue
-<template #actions="slotProps">
-  <NcButton
-    :class="slotProps.actionClass"
-    v-bind="slotProps.actionAttrs"
-    type="button"
-    variant="tertiary"
-    @click.stop="slotProps.onDuplicate"
-  >
-    Duplicate
-  </NcButton>
-</template>
-```
-
-### Theme variables
-
-Action toolbar and action buttons can be themed via CSS variables and follow host theme tokens by default.
-
-| Variable | Description |
-|---|---|
-| `--pdf-elements-toolbar-gap` | Toolbar button gap |
-| `--pdf-elements-toolbar-padding` | Toolbar padding |
-| `--pdf-elements-toolbar-background` | Toolbar background color |
-| `--pdf-elements-toolbar-color` | Toolbar text/icon color |
-| `--pdf-elements-toolbar-border-color` | Toolbar border color |
-| `--pdf-elements-toolbar-border-radius` | Toolbar border radius |
-| `--pdf-elements-toolbar-shadow` | Toolbar shadow |
-| `--pdf-elements-action-btn-border` | Action button border |
-| `--pdf-elements-action-btn-background` | Action button background |
-| `--pdf-elements-action-btn-color` | Action button text/icon color |
-| `--pdf-elements-action-btn-padding` | Action button padding |
-| `--pdf-elements-action-btn-radius` | Action button border radius |
-| `--pdf-elements-action-btn-min-height` | Action button min height |
-| `--pdf-elements-action-btn-min-width` | Action button min width |
-| `--pdf-elements-action-btn-shadow` | Action button shadow |
-| `--pdf-elements-action-btn-hover-background` | Action button hover background |
-
-## Community
-
-Bug reports, feature ideas, documentation improvements, tests and code contributions are welcome.
-
-- Found a bug? [Open a bug report](https://github.com/LibreSign/pdf-elements/issues/new/choose).
-- Have an idea? [Start a feature request](https://github.com/LibreSign/pdf-elements/issues/new/choose).
-- Want to contribute code? Read [CONTRIBUTING.md](CONTRIBUTING.md).
-- Want to understand the project first? Try the [live demo](https://libresign.github.io/pdf-elements/) and inspect the [examples](examples/).
-
-Small, focused pull requests are welcome, including documentation, accessibility, testing and developer-experience improvements.
-
-## License
-
-PDF Elements is free software licensed under the [GNU AGPL-3.0-or-later](COPYING).
-
-The project is maintained by the LibreSign community and LibreCode.
+- [API reference](docs/API.md)
+- [Basic example](examples/basic/)
+- [Contributing](CONTRIBUTING.md)

From fcb9ed687ae6d70e7c475467b16248c5031c1184 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 14:02:18 -0300
Subject: [PATCH 09/11] docs: move API reference out of readme

---
 docs/API.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/API.md

diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..caa0a14
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,105 @@
+<!--
+SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# PDF Elements API
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | String | `'100%'` | Container width |
+| `height` | String | `'100%'` | Container height |
+| `initFiles` | Array | `[]` | PDF files to load |
+| `initFileNames` | Array | `[]` | Names for the PDF files |
+| `initialScale` | Number | `1` | Initial zoom scale |
+| `showPageFooter` | Boolean | `true` | Show page footer with document name and page number |
+| `hideSelectionUI` | Boolean | `false` | Hide selection handles and actions UI |
+| `showSelectionHandles` | Boolean | `true` | Show resize/move handles on selected elements |
+| `showElementActions` | Boolean | `true` | Show action buttons on selected elements |
+| `readOnly` | Boolean | `false` | Disable drag, resize, and actions for elements |
+| `ignoreClickOutsideSelectors` | Array | `[]` | CSS selectors that keep the selection active when clicking outside the element |
+| `pageCountFormat` | String | `'{currentPage} of {totalPages}'` | Format string for page counter |
+| `autoFitZoom` | Boolean | `false` | Automatically adjust zoom to fit viewport on window resize |
+| `pdfjsOptions` | Object | `{}` | Options passed to PDF.js `getDocument` |
+
+## PDF.js options
+
+`pdfjsOptions` is forwarded to PDF.js `getDocument(...)`.
+
+```vue
+<PDFElements
+  :pdfjs-options="{
+    disableFontFace: true,
+    disableRange: true,
+    disableStream: true,
+  }"
+/>
+```
+
+## Events
+
+- `pdf-elements:end-init` - Emitted when PDF is loaded.
+- `pdf-elements:adding-ended` - Emitted when interactive placement ends. Payload: `{ reason: 'placed', object, docIndex, pageIndex }` on success or `{ reason: 'cancelled' }` when placement is cancelled.
+
+## Exposed methods
+
+- `startAddingElement(templateObject)` - Starts interactive placement mode.
+- `cancelAdding()` - Cancels the current placement session and emits `pdf-elements:adding-ended` with `{ reason: 'cancelled' }` when a session was active.
+
+## Slots
+
+- `element-{type}` - Custom element rendering, for example `element-signature`.
+- `custom` - Fallback for elements without a specific type slot.
+- `actions` - Custom action buttons.
+
+### `actions` slot props
+
+The `actions` slot receives:
+
+- `object`
+- `onDelete`
+- `onDuplicate`
+- `toolbarClass` (`pdf-elements-actions-toolbar`)
+- `actionClass` (`pdf-elements-action-btn`)
+- `actionAttrs` (`{ 'data-pdf-elements-action': 'true' }`)
+
+These hooks allow host applications to style third-party button components consistently without depending on internal scoped selectors.
+
+```vue
+<template #actions="slotProps">
+  <NcButton
+    :class="slotProps.actionClass"
+    v-bind="slotProps.actionAttrs"
+    type="button"
+    variant="tertiary"
+    @click.stop="slotProps.onDuplicate"
+  >
+    Duplicate
+  </NcButton>
+</template>
+```
+
+## Theme variables
+
+Action toolbar and action buttons can be themed via CSS variables and follow host theme tokens by default.
+
+| Variable | Description |
+|---|---|
+| `--pdf-elements-toolbar-gap` | Toolbar button gap |
+| `--pdf-elements-toolbar-padding` | Toolbar padding |
+| `--pdf-elements-toolbar-background` | Toolbar background color |
+| `--pdf-elements-toolbar-color` | Toolbar text/icon color |
+| `--pdf-elements-toolbar-border-color` | Toolbar border color |
+| `--pdf-elements-toolbar-border-radius` | Toolbar border radius |
+| `--pdf-elements-toolbar-shadow` | Toolbar shadow |
+| `--pdf-elements-action-btn-border` | Action button border |
+| `--pdf-elements-action-btn-background` | Action button background |
+| `--pdf-elements-action-btn-color` | Action button text/icon color |
+| `--pdf-elements-action-btn-padding` | Action button padding |
+| `--pdf-elements-action-btn-radius` | Action button border radius |
+| `--pdf-elements-action-btn-min-height` | Action button min height |
+| `--pdf-elements-action-btn-min-width` | Action button min width |
+| `--pdf-elements-action-btn-shadow` | Action button shadow |
+| `--pdf-elements-action-btn-hover-background` | Action button hover background |

From 589bd3e13004eaf0f2e2ca28aebd799deb58271a Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 14:06:17 -0300
Subject: [PATCH 10/11] docs: move getting started guide out of readme

---
 README.md | 50 ++------------------------------------------------
 1 file changed, 2 insertions(+), 48 deletions(-)

diff --git a/README.md b/README.md
index 46dfc0d..93b6adb 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ A Vue 3 PDF viewer for building interactive document workflows with draggable, r
 
 Use it to build signature placement, form-field positioning, annotations, review tools, document preparation flows and other PDF experiences where users need to place or manipulate elements on top of a document.
 
-**[Try the live demo](https://libresign.github.io/pdf-elements/)** · **[Install from npm](https://www.npmjs.com/package/@libresign/pdf-elements)** · [Examples](examples/) · [API](docs/API.md) · [Contributing](CONTRIBUTING.md)
+**[Try the live demo](https://libresign.github.io/pdf-elements/)** · [Getting started](docs/GETTING_STARTED.md) · [API](docs/API.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)
 
 ![The pdf-elements demo with a sample PDF loaded and a signature element placed on the first page](img/screenshot/demo.png)
 
@@ -35,53 +35,6 @@ PDF Elements provides that interaction layer as a reusable Vue 3 component.
 
 PDF Elements does **not** cryptographically sign or modify the PDF by itself. It focuses on the browser interaction layer, so it can be connected to signing, storage, form or document-processing backends.
 
-## Install
-
-```bash
-npm install @libresign/pdf-elements
-```
-
-## Quick start
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import PDFElements from '@libresign/pdf-elements'
-
-const pdf = ref()
-const files = ref([
-  'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf',
-])
-
-function addSignatureField() {
-  pdf.value?.startAddingElement({
-    type: 'signature',
-    width: 160,
-    height: 48,
-    label: 'Signature',
-  })
-}
-</script>
-
-<template>
-  <button @click="addSignatureField">
-    Add signature field
-  </button>
-
-  <PDFElements
-    ref="pdf"
-    :init-files="files"
-    :init-file-names="['sample.pdf']"
-  >
-    <template #element-signature="{ object }">
-      <div>{{ object.label }}</div>
-    </template>
-  </PDFElements>
-</template>
-```
-
-For a fuller integration with custom controls, actions and document handling, see the [basic example](examples/basic/).
-
 ## Use cases
 
 PDF Elements can be used for:
@@ -95,6 +48,7 @@ PDF Elements can be used for:
 
 ## Documentation
 
+- [Getting started](docs/GETTING_STARTED.md)
 - [API reference](docs/API.md)
 - [Basic example](examples/basic/)
 - [Contributing](CONTRIBUTING.md)

From 7f742913a8b4368daebedfbcf1d6d2841e0c1b93 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Mon, 28 Sep 2026 14:06:19 -0300
Subject: [PATCH 11/11] docs: add getting started guide

---
 docs/GETTING_STARTED.md | 55 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/GETTING_STARTED.md

diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
new file mode 100644
index 0000000..a9d7109
--- /dev/null
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,55 @@
+<!--
+SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Getting started
+
+## Install
+
+```bash
+npm install @libresign/pdf-elements
+```
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import PDFElements from '@libresign/pdf-elements'
+
+const pdf = ref()
+const files = ref([
+  'https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf',
+])
+
+function addSignatureField() {
+  pdf.value?.startAddingElement({
+    type: 'signature',
+    width: 160,
+    height: 48,
+    label: 'Signature',
+  })
+}
+</script>
+
+<template>
+  <button @click="addSignatureField">
+    Add signature field
+  </button>
+
+  <PDFElements
+    ref="pdf"
+    :init-files="files"
+    :init-file-names="['sample.pdf']"
+  >
+    <template #element-signature="{ object }">
+      <div>{{ object.label }}</div>
+    </template>
+  </PDFElements>
+</template>
+```
+
+For a fuller integration with custom controls, actions and document handling, see the [basic example](../examples/basic/).
+
+For the available props, events, methods, slots and theme variables, see the [API reference](API.md).