docs(pdf): @rozie-ui/pdf showcase + comparison + live-demo (3rd-page standard)

Showcase (quick starts x6, validated Props table [10 rows], Events, 12-verb
handle, recipes, gotchas — worker/standardFontDataUrl/no-CSS-import), libraries
comparison (react-pdf deep / ng2-pdf-viewer + vue-pdf-embed moderate / Svelte
thin / Solid+Lit nothing), and a live-demo page running the real @rozie-ui/pdf-vue
package: a 3-page PDF with selectable text layer, page nav + zoom + rotate +
continuous-scroll toggle via the handle, bundled worker via new URL().

Sidebar + rozie-codegen product + docs deps (@rozie-ui/pdf-vue, pdfjs-dist).
Verified: vitepress build clean (143 anchors, 0 broken); headless render confirms
canvas + text layer (selectable spans) render, readout 'page 1/3', Next->2/3.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serpentblade

docs/.vitepress/config.ts

@@ -167,6 +167,14 @@ export default defineConfig({
             { text: 'Cropper — live demo', link: '/guide/cropper-demo' },
           ],
         },
+        {
+          text: '@rozie-ui/pdf',
+          items: [
+            { text: 'PdfViewer — showcase & API', link: '/guide/pdf' },
+            { text: 'PDF libraries comparison', link: '/guide/pdf-comparison' },
+            { text: 'PdfViewer — live demo', link: '/guide/pdf-demo' },
+          ],
+        },
       ],
       '/compatibility': [
         {

docs/.vitepress/rozie-codegen.ts

@@ -61,7 +61,7 @@ export function rozieCodegen(
     // `SortableList` moved there in Phase 20-01 and `Flatpickr` in the
     // flatpickr port, so docs resolve their canonical producer from the
     // package source rather than the (now-removed) `examples/<Name>.rozie`.
-    for (const product of ['sortable-list', 'flatpickr', 'fullcalendar', 'codemirror', 'chartjs', 'tiptap', 'maplibre', 'cropper']) {
+    for (const product of ['sortable-list', 'flatpickr', 'fullcalendar', 'codemirror', 'chartjs', 'tiptap', 'maplibre', 'cropper', 'pdf']) {
       const pkgSrc = resolve(
         opts.examplesDir,
         '..',

docs/guide/pdf-comparison.md

@@ -0,0 +1,67 @@
+# PDF libraries comparison
+
+How `@rozie-ui/pdf` compares to the existing per-framework [PDF.js](https://mozilla.github.io/pdf.js/) wrappers. PDF.js (mozilla/pdf.js, shipped as `pdfjs-dist`) is the de-facto vanilla-JS PDF rendering engine, and it is framework-agnostic: every wrapper exists only to glue reactive state to PDF.js's imperative `getDocument()` / `page.render()` flow, configure the Web Worker, render the page canvas (and, for the good ones, the selectable text layer), and forward the page / load events. The result is a **lopsided ecosystem**: a deep, maintained React wrapper; decent Vue and Angular options; a **thin Svelte story; and effectively nothing for Solid or Lit**. Rozie ships one source to all six.
+
+> Research snapshot: 2026-06-08. Versions and the wrapper landscape move; treat them as of that date. Note `@react-pdf/renderer` is a different library — it *generates* PDFs from React components; it is **not** a viewer, so it's out of scope here.
+
+## The wrappers at a glance
+
+| Framework | PDF.js wrapper | Engine | Depth | Notes |
+| --- | --- | --- | :---: | --- |
+| **React** | `react-pdf` (wojtekmaj) | `pdfjs-dist` | **deep** | Mature, actively maintained, the obvious React pick. |
+| **Vue** | `vue-pdf-embed` (+ `@tato30/vue-pdf`) | `pdfjs-dist` | **moderate** | Maintained, reasonable surface; less deep than `react-pdf`. |
+| **Angular** | `ng2-pdf-viewer` | `pdfjs-dist` | **moderate** | Popular, widely used; maintenance has slowed (last publish 2024). |
+| **Svelte** | `svelte-pdf` / community wrappers | `pdfjs-dist` | **thin** | Sparse surface, lower adoption, no text-layer story. |
+| **Solid** | *(none)* | — | — | No dedicated PDF.js (or comparable) viewer wrapper. |
+| **Lit** | *(none)* | — | — | No web-component viewer; PDF.js's own prebuilt viewer is an iframe-embedded *app*, not a component. |
+| **Rozie** | `@rozie-ui/pdf-*` | `pdfjs-dist` v6 | **deep** | One source → all six, same props / two-way `page` / events / handle / text layer. |
+
+`react-pdf` is an **excellent, mature library** — for a single-React app it's the obvious pick, and Rozie does not claim to out-feature it on React. `vue-pdf-embed` and `ng2-pdf-viewer` are likewise **solid choices on their home framework**. The wedge is the underserved targets: Svelte's options are **thin** (`svelte-pdf` is sparse, low-adoption, with no selectable-text-layer story), and **Solid and Lit have nothing at all** — a Lit dev's only "option" is embedding PDF.js's prebuilt viewer-app in an iframe, which is a whole application, not a component. Rozie gives all three underserved targets a real, *consistent* embeddable PDF viewer — the same one it produces for React — from a single definition, with one uniform API across all six.
+
+## Feature matrix
+
+Cell legend: **✅** = documented out-of-the-box · **❌** = not supported / not present · **⚠️** = partial / consumer-glue-required / thin.
+
+| Capability | `react-pdf` | `vue-pdf-embed` | `ng2-pdf-viewer` | `svelte-pdf` | Solid (none) | Lit (none) | **`@rozie-ui/pdf`** |
+| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| Mount from URL | ✅ | ✅ | ✅ | ✅ | hand-roll | hand-roll | ✅ `:src` |
+| Mount from data (`Uint8Array` / `ArrayBuffer`) | ✅ | ✅ | ✅ | ⚠️ | hand-roll | hand-roll | ✅ `:src` (+ `data:` URL decode) |
+| **Two-way current page** | ⚠️ via state | ⚠️ via prop | ⚠️ `[page]` + `(pageChange)` | ⚠️ | — | — | ✅ `r-model:page` (echo-guarded) |
+| Continuous scroll (all pages) | ✅ | ✅ | ✅ | ⚠️ | — | — | ✅ `render-all-pages` |
+| Single-page mode | ✅ | ✅ | ✅ | ✅ | — | — | ✅ (default) |
+| Zoom | ✅ | ✅ | ✅ | ⚠️ | — | — | ✅ `:scale` + zoom verbs |
+| Rotation | ✅ | ✅ | ✅ | ⚠️ | — | — | ✅ `:rotation` + rotate verbs |
+| **Selectable text layer** | ✅ | ✅ | ✅ | ❌ | — | — | ✅ `text-layer` (default on, CSS shipped) |
+| Imperative handle | ⚠️ via refs | ⚠️ partial | ⚠️ via methods | ❌ | hand-roll | hand-roll | ✅ uniform 12-verb `$expose` |
+| Password-protected PDFs | ✅ | ✅ | ✅ | ⚠️ | — | — | ✅ `:password` + `passwordrequest` event |
+| TypeScript | ✅ | ✅ | ✅ | ⚠️ | — | — | ✅ |
+| One source → all 6 frameworks | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+
+## Where Rozie wins today
+
+- **One definition, six idiomatic packages** — including the three frameworks the ecosystem underserves: **Svelte (thin `svelte-pdf`, no text layer), Solid (nothing), and Lit (nothing but an iframe-embedded viewer-app)**. A Svelte dev today fights a sparse, low-adoption wrapper; a Solid or Lit dev hand-rolls the whole worker / `getDocument` / canvas / text-layer flow. Rozie hands all three a first-class PDF viewer with selectable text, page nav, zoom and rotation.
+- **A real two-way current page on all six** — `r-model:page` (1-based) reads *and* drives which page renders in single mode, and in `render-all-pages` mode it reflects the scrolled-to page back via an `IntersectionObserver` (and the `pagechange` event), with an echo-guard so a consumer write and the scroll-spy don't fight. The incumbents surface the page via a one-way prop plus a separate change event; you wire the round-trip yourself.
+- **A selectable text layer that just works** — `text-layer` is on by default and renders PDF.js's text spans over each page canvas so text is copyable / searchable. The required `.textLayer` CSS and the `--scale-factor` var ship *with the component* (via the `:root {}` engine-DOM escape hatch), so there's **no extra CSS import**. This is exactly what `svelte-pdf` lacks and what a hand-rolled Solid / Lit viewer rarely gets right.
+- **A uniform 12-verb imperative handle** (`getDocument` / `getPageCount` / `goToPage` / `nextPage` / `prevPage` / `setScale` / `zoomIn` / `zoomOut` / `fitWidth` / `fitPage` / `rotateCW` / `rotateCCW`) grabbed with each framework's native ref — identical on every target, versus "however this wrapper happens to expose things." The verbs drive the internal render state, so they work whether or not the consumer two-way-binds `page`.
+- **Zero-config worker** — the #1 PDF.js integration friction is `GlobalWorkerOptions.workerSrc`. The `worker-src` prop defaults to the version-matched CDN copy, so the component renders with no setup; override it (`:worker-src`) for offline / CSP / bundled-worker builds. Standard-font data is wired the same way (`:standard-font-data-url`).
+- **`getDocument()` is always one hop from the raw engine**, so the full `pdfjs-dist` API (annotation extraction, outline, metadata, custom render flows) is reachable on any target when the curated surface doesn't cover something.
+
+## What Rozie defers {#what-rozie-defers}
+
+This page concedes where the standalone wrappers and PDF.js's own viewer are genuinely ahead — that's what keeps the comparison credible, and it doubles as Rozie's own roadmap.
+
+- **Annotation layer / form fields (AcroForm).** `react-pdf` and PDF.js's full prebuilt viewer render the **annotation layer** — links, widget annotations, and interactive AcroForm form fields. Rozie v1 renders the **page canvas + the selectable text layer**, not the annotation layer, so links aren't clickable and form fields aren't fillable inside the component. This is a meaningful piece of PDF.js (`AnnotationLayer` + the annotation storage / form value plumbing), deliberately deferred rather than half-shipped. Until then, `getDocument()` hands you the raw `PDFDocumentProxy` so you can drive the annotation layer yourself.
+- **Search UI, thumbnails sidebar, print / download chrome.** PDF.js's full prebuilt **viewer application** ships find-in-document, a thumbnail sidebar, print and download toolbars, and presentation mode. Rozie ships the **embeddable viewer component**, not the full viewer-app chrome. The underlying data is all reachable — `getDocument()` exposes the raw pdfjs document for custom search / thumbnail / print UI — but Rozie doesn't bundle that chrome.
+- **Big-framework depth on the home framework.** `react-pdf` is a mature, multi-year library with deep React-idiomatic ergonomics, broad edge-case handling, and a large user base; `vue-pdf-embed` and `ng2-pdf-viewer` are likewise well-worn on their own frameworks. On their home framework each exposes more accumulated polish than Rozie's curated prop set. Rozie's value is **not** "more than `react-pdf` on React" — it's the **same idiomatic component on all six frameworks from one source**, with the underserved **Svelte / Solid / Lit** getting a viewer they otherwise lack. For anything outside the curated surface, `getDocument()` hands you the raw engine on every target.
+- **`@rozie-ui/pdf` is `0.1.0`.** The surface (10 props / 5 events / 12-verb handle / two-way `page` model / selectable text layer / single + continuous render modes) is stable and gate-verified, but it is younger than the multi-year incumbents.
+
+## Try it
+
+The [`@rozie-ui/pdf` showcase + API reference](/guide/pdf) documents the `@rozie-ui/pdf-*` packages — one pre-compiled, per-framework install (`npm i @rozie-ui/pdf-react pdfjs-dist`, etc.). The PDF.js Web Worker **auto-configures** from the version-matched CDN, so there's nothing extra to import to render a PDF (override `:worker-src` for offline / CSP / bundled-worker builds). The showcase walks the two-way `page` binding, single vs `render-all-pages` modes, the selectable text layer, zoom / rotation, password-protected PDFs, and the 12-verb imperative handle. The [live demo](/guide/pdf-demo) runs the component across all six targets.
+
+## Cross-references
+
+- [PDF — showcase & API](/guide/pdf) — the full `@rozie-ui/pdf` surface, quick starts, and recipes.
+- [PDF — live demo](/guide/pdf-demo) — the viewer running across all six targets.
+- [`PdfViewer.rozie` source on GitHub](https://github.com/One-Learning-Community/rozie.js/blob/main/packages/ui/pdf/src/PdfViewer.rozie)
+- [Cropper libraries comparison](/guide/cropper-comparison) — the sibling engine-wrapper port.

docs/guide/pdf-demo.md

@@ -0,0 +1,150 @@
+---
+title: PdfViewer — live demo
+---
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import PdfViewer from '@rozie-ui/pdf-vue';
+
+// Bundle the PDF.js worker locally via Vite's `new URL(...)` so the demo needs no
+// CDN for the worker (the recommended override for bundler setups — the prop
+// otherwise defaults to a CDN copy).
+const workerSrc = new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).toString();
+
+// A self-contained 3-page PDF (base64 data URL) — network-free, so the demo works
+// offline / in CI.
+const SAMPLE =
+  'data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago8PC9UeXBlL1BhZ2VzL0tpZHNbNCAwIFIgNSAwIFIgNiAwIFJdL0NvdW50IDM+PgplbmRvYmoKMyAwIG9iago8PC9UeXBlL0ZvbnQvU3VidHlwZS9UeXBlMS9CYXNlRm9udC9IZWx2ZXRpY2E+PgplbmRvYmoKNCAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50IDIgMCBSL01lZGlhQm94WzAgMCA2MTIgNzkyXS9SZXNvdXJjZXM8PC9Gb250PDwvRjEgMyAwIFI+Pj4+L0NvbnRlbnRzIDcgMCBSPj4KZW5kb2JqCjUgMCBvYmoKPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgNjEyIDc5Ml0vUmVzb3VyY2VzPDwvRm9udDw8L0YxIDMgMCBSPj4+Pi9Db250ZW50cyA4IDAgUj4+CmVuZG9iago2IDAgb2JqCjw8L1R5cGUvUGFnZS9QYXJlbnQgMiAwIFIvTWVkaWFCb3hbMCAwIDYxMiA3OTJdL1Jlc291cmNlczw8L0ZvbnQ8PC9GMSAzIDAgUj4+Pj4vQ29udGVudHMgOSAwIFI+PgplbmRvYmoKNyAwIG9iago8PC9MZW5ndGggMTI3Pj4Kc3RyZWFtCkJUIC9GMSAyOCBUZiA2MCA3MDAgVGQgKFJvemllIFBERiB2aWV3ZXIgIC0gIHBhZ2UgMSkgVGogMCAtNDAgVGQgL0YxIDE0IFRmIChUaGUgcXVpY2sgYnJvd24gZm94IGp1bXBzIG92ZXIgdGhlIGxhenkgZG9nLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago4IDAgb2JqCjw8L0xlbmd0aCAxMzc+PgpzdHJlYW0KQlQgL0YxIDI4IFRmIDYwIDcwMCBUZCAoT25lIHNvdXJjZSwgc2l4IGZyYW1ld29ya3MgIC0gIHBhZ2UgMikgVGogMCAtNDAgVGQgL0YxIDE0IFRmIChUaGUgcXVpY2sgYnJvd24gZm94IGp1bXBzIG92ZXIgdGhlIGxhenkgZG9nLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjw8L0xlbmd0aCAxNDU+PgpzdHJlYW0KQlQgL0YxIDI4IFRmIDYwIDcwMCBUZCAoU2VsZWN0YWJsZSB0ZXh0IHZpYSB0aGUgdGV4dCBsYXllciAgLSAgcGFnZSAzKSBUaiAwIC00MCBUZCAvRjEgMTQgVGYgKFRoZSBxdWljayBicm93biBmb3gganVtcHMgb3ZlciB0aGUgbGF6eSBkb2cuKSBUaiBFVAplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCAxMAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTE3IDAwMDAwIG4gCjAwMDAwMDAxODAgMDAwMDAgbiAKMDAwMDAwMDI5MiAwMDAwMCBuIAowMDAwMDAwNDA0IDAwMDAwIG4gCjAwMDAwMDA1MTYgMDAwMDAgbiAKMDAwMDAwMDY5MiAwMDAwMCBuIAowMDAwMDAwODc4IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxMC9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjEwNzIKJSVFT0Y=';
+
+const viewer = ref();
+const page = ref(1);
+const total = ref(0);
+const allPages = ref(false);
+</script>
+
+# PdfViewer — live demo
+
+This is the **real `@rozie-ui/pdf-vue` package** running on this page (VitePress is itself a Vue app), rendering a 3-page PDF via PDF.js. Page through it, zoom, rotate, toggle continuous scroll — and **select the text** (it's a real text layer, not an image). All of it is driven by the one `PdfViewer.rozie` source that compiles to six frameworks.
+
+<ClientOnly>
+<div class="pdf-live">
+  <div class="pdf-live__controls">
+    <button @click="viewer?.prevPage()" :disabled="page <= 1">‹ Prev</button>
+    <span class="pdf-live__readout">page {{ page }} / {{ total || '…' }}</span>
+    <button @click="viewer?.nextPage()" :disabled="page >= total">Next ›</button>
+    <span class="pdf-live__sep" />
+    <button @click="viewer?.zoomOut()">Zoom −</button>
+    <button @click="viewer?.zoomIn()">Zoom +</button>
+    <button @click="viewer?.fitWidth()">Fit width</button>
+    <button @click="viewer?.rotateCW()">Rotate ⟳</button>
+    <span class="pdf-live__sep" />
+    <button :class="{ 'pdf-live__primary': allPages }" @click="allPages = !allPages">
+      {{ allPages ? 'Continuous ✓' : 'Continuous' }}
+    </button>
+  </div>
+
+  <div class="pdf-live__stage">
+    <PdfViewer
+      ref="viewer"
+      :src="SAMPLE"
+      :worker-src="workerSrc"
+      v-model:page="page"
+      :render-all-pages="allPages"
+      @load="(e) => (total = e.numPages)"
+    />
+  </div>
+
+  <p class="pdf-live__hint">Tip: drag-select the text on a page — it's copyable.</p>
+</div>
+</ClientOnly>
+
+The current page is two-way bound with `v-model:page` (the readout tracks it as you scroll in continuous mode), and the buttons drive the imperative handle (`prevPage` / `nextPage` / `zoomIn` / `zoomOut` / `fitWidth` / `rotateCW`). The worker is bundled locally here via `new URL(...)`; left unset it defaults to a CDN copy. See the [full API](/guide/pdf) for every prop, event, and handle verb.
+
+## One source, six outputs
+
+You author the component **once** as a `.rozie` file:
+
+<<< ../../packages/ui/pdf/src/PdfViewer.rozie{html}[PdfViewer.rozie — the single source]
+
+…and Rozie compiles it to six idiomatic, framework-native components. Switch the tabs to see the **actual generated output** for each target (this is exactly what ships in `@rozie-ui/pdf-{react,vue,svelte,angular,solid,lit}`):
+
+::: code-group
+
+<<< ../../packages/ui/pdf/packages/react/src/PdfViewer.tsx[React]
+<<< ../../packages/ui/pdf/packages/vue/src/PdfViewer.vue[Vue]
+<<< ../../packages/ui/pdf/packages/svelte/src/PdfViewer.svelte[Svelte]
+<<< ../../packages/ui/pdf/packages/angular/src/PdfViewer.ts[Angular]
+<<< ../../packages/ui/pdf/packages/solid/src/PdfViewer.tsx[Solid]
+<<< ../../packages/ui/pdf/packages/lit/src/PdfViewer.ts[Lit]
+
+:::
+
+Each is a real, idiomatic component for its framework — React `forwardRef` + hooks, Vue `<script setup>` + `defineModel`, Svelte 5 runes, an Angular standalone component, a Solid component, and a Lit custom element — with the same props, events, and 12-verb imperative handle, all from the one source above.
+
+## See also
+
+- [PdfViewer — showcase & API](/guide/pdf) — install, quick starts for all six frameworks, the worker setup, and the full reference.
+- [PDF libraries comparison](/guide/pdf-comparison) — how `@rozie-ui/pdf` stacks up against react-pdf, vue-pdf-embed, ng2-pdf-viewer, and the underserved frameworks.
+
+<style scoped>
+.pdf-live {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft);
+}
+.pdf-live__controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.85rem;
+}
+.pdf-live__controls button {
+  font: inherit;
+  font-size: 0.82rem;
+  padding: 0.3rem 0.7rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 7px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+.pdf-live__controls button:hover:not(:disabled) {
+  border-color: var(--vp-c-brand-1);
+  color: var(--vp-c-brand-1);
+}
+.pdf-live__controls button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+.pdf-live__controls button.pdf-live__primary {
+  background: var(--vp-c-brand-1);
+  border-color: var(--vp-c-brand-1);
+  color: #fff;
+  font-weight: 600;
+}
+.pdf-live__sep {
+  width: 1px;
+  align-self: stretch;
+  margin: 0 0.3rem;
+  background: var(--vp-c-divider);
+}
+.pdf-live__readout {
+  font-size: 0.82rem;
+  font-variant-numeric: tabular-nums;
+  color: var(--vp-c-text-2);
+}
+.pdf-live__stage {
+  height: 480px;
+  border-radius: 8px;
+  overflow: hidden;
+}
+.pdf-live__hint {
+  margin: 0.6rem 0 0;
+  font-size: 0.8rem;
+  color: var(--vp-c-text-3);
+}
+</style>