fix(ui-pdf): drive PdfViewer find via reactive :query prop (fixes Angular VR)

The find re-port (d581e01/ddd852ee) wired the PdfViewerDemo "Find" button to
the imperative $expose handle (`$refs.viewer.find($data.query)`). On Angular a
child-component `ref` inside a @click listener compiles to a template-local
`ɵɵreference` that is out of scope in the listener closure, so clicking Find
threw `TypeError: viewer_r2 is not a function` and find-readout stayed 0 — the
exact non-uniformity the demo header already documented for page-nav (which is
why `page` is driven by a two-way model, not the handle). PdfViewerDemo was the
only demo driving a child handle from @click.

Fix: add a controlled, reactive `query` prop to PdfViewer (the search analog of
the `page` model). A lazy $watch runs find()/clearFind() on a consumer write, so
find works uniformly across all six targets with no handle call. The demo's Find
button now copies the input into `:query`; the imperative find/findNext/… verbs
remain in $expose (structural + docs coverage).

- PdfViewer.rozie: +query prop, +lazy $watch(query) → find/clearFind
- PdfViewerDemo.rozie: Find/Clear drive :query, drop unused ref + Next-match handle button
- regenerate 6 leaves + READMEs + docs props-table (11 props); surface gate 10→11 props
- verified: pdf.spec.ts 6/6 green (angular + lit + react …), pdf-* leaf typecheck 10/10

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lxeam8c3XSttraCZPxufKM

Author: serpentblade

docs/components/pdf.md

@@ -181,6 +181,7 @@ el.addEventListener('load', (e) => console.log(e.detail.numPages));
 | `renderAllPages` | `Boolean` | `false` | | ✓ | `false` = single page with nav (the two-way `page` drives it). `true` = continuous scroll of every page; the most-visible page reflects back into `page` and the `pagechange` event via an `IntersectionObserver`. |
 | `textLayer` | `Boolean` | `true` | | ✓ | Render PDF.js's selectable / copyable text-layer spans over each page canvas (the differentiator vs a dumb canvas image). The required `.textLayer` CSS + `--scale-factor` var ship with the component — no extra import. |
 | `password` | `unknown` | `undefined` | | ✓ | Password for an encrypted PDF. If the document is encrypted and no (or a wrong) password is set, the `passwordrequest` event fires with `{ reason }`. Changing it reloads the document. |
+| `query` | `unknown` | `undefined` | | ✓ | A reactive search query — the **controlled** alternative to the imperative `find()` handle. Setting it to a non-empty string scans every page, navigates to + coarse-highlights the first match, and emits `findresult` with the total occurrence count; clearing it (empty string / `null`) clears the highlight. Reactive so it works uniformly across all six targets (an Angular child-component `ref` cannot reach the `$expose` handle from a template event handler — the same reason `page` is a two-way model rather than a handle call). |
 | `options` | `Object` | `{}` | | ✓ | Raw [`getDocument` `DocumentInitParameters`](https://mozilla.github.io/pdf.js/api/draft/module-pdfjsLib.html) passthrough — spread **before** the curated keys (explicit `src` / `password` win). For `cMapUrl`, `httpHeaders`, `withCredentials`, etc. |
 
 ### Events

examples/demos/PdfViewerDemo.rozie

@@ -27,6 +27,15 @@
       uniform across all 6 — an Angular child-component ref resolves to the host
       element, not the instance, so a handle-driven Next would no-op there. The
       $expose handle (nextPage/zoomIn/…) is covered structurally + in the docs.
+    - Find is driven through the CONTROLLED `:query` prop (NOT the $expose handle):
+      the "Find" button copies the input's text into $data.active, which flows into
+      the wrapper's `:query` prop → its lazy $watch runs find() → emits `findresult`
+      → onFind mirrors the count into the readout. This mirrors the two-way `page`
+      model: an Angular child-component `ref` can't reach the $expose handle from a
+      template event handler (a handle-driven `$refs.viewer.find()` throws
+      "viewer_r2 is not a function" there), so the demo stays uniform across all 6
+      by driving reactive props, never the handle. The find/findNext/… handle verbs
+      are covered structurally + in the docs.
     - standardFontDataUrl is left at its default; offline (Docker) it can't load,
       so glyphs may fall back — fine, the spec asserts a .textLayer span exists
       (selectable text present), not its exact glyphs.
@@ -47,6 +56,10 @@
   page: 1,
   total: 0,
   query: 'fox',
+  // the CONTROLLED search query handed to the wrapper's `:query` prop. Starts
+  // empty so the wrapper's lazy $watch does not run a find on mount; the "Find"
+  // button copies $data.query into it to trigger the search.
+  active: '',
   findCount: 0,
 }
 </data>
@@ -86,6 +99,12 @@ const onFind = (e) => {
   const m = e && e.detail && typeof e.detail.matches === 'number' ? e.detail.matches : e.matches
   $data.findCount = m
 }
+
+// run the search by copying the query into the CONTROLLED `:query` prop (the
+// wrapper's lazy $watch runs find()) — NOT the imperative handle, so it works
+// uniformly across all six targets. Clearing it resets the highlight.
+const runFind = () => { $data.active = $data.query }
+const clearSearch = () => { $data.active = '' }
 </script>
 
 <template>
@@ -99,17 +118,16 @@ const onFind = (e) => {
 
   <div class="controls">
     <input type="text" data-testid="find-input" r-model="$data.query" />
-    <button type="button" data-testid="find" @click="$refs.viewer && $refs.viewer.find($data.query)">Find</button>
-    <button type="button" data-testid="find-next" @click="$refs.viewer && $refs.viewer.findNext()">Next match</button>
-    <button type="button" data-testid="find-clear" @click="$refs.viewer && $refs.viewer.clearFind()">Clear</button>
+    <button type="button" data-testid="find" @click="runFind">Find</button>
+    <button type="button" data-testid="find-clear" @click="clearSearch">Clear</button>
     <span class="readout">matches <b data-testid="find-readout">{{ $data.findCount }}</b></span>
   </div>
 
   <div class="pdf-wrap" style="height: 360px">
     <PdfViewer
-      ref="viewer"
       :src="SAMPLE"
       :worker-src="workerSrc"
+      :query="$data.active"
       r-model:page="$data.page"
       @load="onLoad"
       @findresult="onFind"

packages/ui/pdf/packages/angular/README.md

@@ -51,6 +51,7 @@ export class DemoComponent {
 | `renderAllPages` | `Boolean` | `false` |  |  |
 | `textLayer` | `Boolean` | `true` |  |  |
 | `password` | `unknown` | `undefined` |  |  |
+| `query` | `unknown` | `undefined` |  |  |
 | `options` | `Object` | `{}` |  |  |
 
 ## Events

packages/ui/pdf/packages/angular/src/PdfViewer.ts

@@ -109,6 +109,10 @@ export class PdfViewer {
    * Password for an encrypted PDF. If the document is encrypted and no (or a wrong) password is set, the `passwordrequest` event fires with `{ reason }`. Changing it reloads the document.
    */
   password = input<unknown>(undefined);
+  /**
+   * A reactive search query — the **controlled** alternative to the imperative `find()` handle. Setting it to a non-empty string scans every page, navigates to + coarse-highlights the first match, and emits `findresult` with the total occurrence count; clearing it (empty string / `null`) clears the highlight. Reactive so it works uniformly across all six targets (an Angular child-component `ref` cannot reach the `$expose` handle from a template event handler — the same reason `page` is a two-way model rather than a handle call).
+   */
+  query = input<unknown>(undefined);
   /**
    * Raw `getDocument` `DocumentInitParameters` passthrough — spread **before** the curated keys (explicit `src` / `password` win). For `cMapUrl`, `httpHeaders`, `withCredentials`, etc.
    */
@@ -138,6 +142,7 @@ export class PdfViewer {
   private __rozieWatchInitial_9 = true;
   private __rozieWatchInitial_10 = true;
   private __rozieWatchInitial_11 = true;
+  private __rozieWatchInitial_12 = true;
 
   constructor() {
     effect(() => { const __watchVal = (() => this.engineReady())(); untracked(() => { if (this.__rozieWatchInitial_0) { this.__rozieWatchInitial_0 = false; return; } (() => this._load())(); }); });
@@ -168,6 +173,11 @@ export class PdfViewer {
     effect(() => { const __watchVal = (() => this.rot())(); untracked(() => { if (this.__rozieWatchInitial_9) { this.__rozieWatchInitial_9 = false; return; } (() => this.renderView())(); }); });
     effect(() => { const __watchVal = (() => this.renderAllPages())(); untracked(() => { if (this.__rozieWatchInitial_10) { this.__rozieWatchInitial_10 = false; return; } (() => this.renderView())(); }); });
     effect(() => { const __watchVal = (() => this.textLayer())(); untracked(() => { if (this.__rozieWatchInitial_11) { this.__rozieWatchInitial_11 = false; return; } (() => this.renderView())(); }); });
+    effect(() => { const __watchVal = (() => this.query())(); untracked(() => { if (this.__rozieWatchInitial_12) { this.__rozieWatchInitial_12 = false; return; } ((v: any) => {
+      if (v == null) return;
+      const q = String(v);
+      if (q) this.find(q);else this.clearFind();
+    })(__watchVal); }); });
   }
 
   ngAfterViewInit() {

packages/ui/pdf/packages/lit/README.md

@@ -39,6 +39,7 @@ el.addEventListener('load', (e) => console.log(e.detail.numPages));
 | `renderAllPages` | `Boolean` | `false` |  |  |
 | `textLayer` | `Boolean` | `true` |  |  |
 | `password` | `unknown` | `undefined` |  |  |
+| `query` | `unknown` | `undefined` |  |  |
 | `options` | `Object` | `{}` |  |  |
 
 ## Events

packages/ui/pdf/packages/lit/src/PdfViewer.ts

@@ -96,6 +96,10 @@ export default class PdfViewer extends SignalWatcher(LitElement) {
    * Password for an encrypted PDF. If the document is encrypted and no (or a wrong) password is set, the `passwordrequest` event fires with `{ reason }`. Changing it reloads the document.
    */
   @property({ type: Object }) password: unknown = undefined;
+  /**
+   * A reactive search query — the **controlled** alternative to the imperative `find()` handle. Setting it to a non-empty string scans every page, navigates to + coarse-highlights the first match, and emits `findresult` with the total occurrence count; clearing it (empty string / `null`) clears the highlight. Reactive so it works uniformly across all six targets (an Angular child-component `ref` cannot reach the `$expose` handle from a template event handler — the same reason `page` is a two-way model rather than a handle call).
+   */
+  @property({ type: Object }) query: unknown = undefined;
   /**
    * Raw `getDocument` `DocumentInitParameters` passthrough — spread **before** the curated keys (explicit `src` / `password` win). For `cMapUrl`, `httpHeaders`, `withCredentials`, etc.
    */
@@ -185,6 +189,11 @@ private __rozieFirstUpdateDone = false;
     })(__watchVal); }
     if (this.__rozieFirstUpdateDone && (changedProperties.has('renderAllPages'))) { const __watchVal = (() => this.renderAllPages)(); (() => this.renderView())(); }
     if (this.__rozieFirstUpdateDone && (changedProperties.has('textLayer'))) { const __watchVal = (() => this.textLayer)(); (() => this.renderView())(); }
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('query'))) { const __watchVal = (() => this.query)(); ((v: any) => {
+      if (v == null) return;
+      const q = String(v);
+      if (q) this.find(q);else this.clearFind();
+    })(__watchVal); }
     this.__rozieFirstUpdateDone = true;
   }
 
@@ -648,7 +657,7 @@ private __rozieFirstUpdateDone = false;
    * (explicit `attribute:`) AND lowercased property name (Lit's default).
    */
   private get $attrs(): Record<string, string> {
-    const __skip = new Set<string>(['src', 'page', 'scale', 'rotation', 'worker-src', 'workersrc', 'standard-font-data-url', 'standardfontdataurl', 'render-all-pages', 'renderallpages', 'text-layer', 'textlayer', 'password', 'options']);
+    const __skip = new Set<string>(['src', 'page', 'scale', 'rotation', 'worker-src', 'workersrc', 'standard-font-data-url', 'standardfontdataurl', 'render-all-pages', 'renderallpages', 'text-layer', 'textlayer', 'password', 'query', 'options']);
     const out: Record<string, string> = {};
     for (const a of Array.from(this.attributes)) {
       if (__skip.has(a.name)) continue;

packages/ui/pdf/packages/react/README.md

@@ -46,6 +46,7 @@ export function Demo() {
 | `renderAllPages` | `Boolean` | `false` |  |  |
 | `textLayer` | `Boolean` | `true` |  |  |
 | `password` | `unknown` | `undefined` |  |  |
+| `query` | `unknown` | `undefined` |  |  |
 | `options` | `Object` | `{}` |  |  |
 
 ## Events

packages/ui/pdf/packages/react/src/PdfViewer.d.ts

@@ -43,6 +43,10 @@ export interface PdfViewerProps {
    * Password for an encrypted PDF. If the document is encrypted and no (or a wrong) password is set, the `passwordrequest` event fires with `{ reason }`. Changing it reloads the document.
    */
   password?: unknown;
+  /**
+   * A reactive search query — the **controlled** alternative to the imperative `find()` handle. Setting it to a non-empty string scans every page, navigates to + coarse-highlights the first match, and emits `findresult` with the total occurrence count; clearing it (empty string / `null`) clears the highlight. Reactive so it works uniformly across all six targets (an Angular child-component `ref` cannot reach the `$expose` handle from a template event handler — the same reason `page` is a two-way model rather than a handle call).
+   */
+  query?: unknown;
   /**
    * Raw `getDocument` `DocumentInitParameters` passthrough — spread **before** the curated keys (explicit `src` / `password` win). For `cMapUrl`, `httpHeaders`, `withCredentials`, etc.
    */

packages/ui/pdf/packages/react/src/PdfViewer.tsx

@@ -44,6 +44,10 @@ interface PdfViewerProps {
    * Password for an encrypted PDF. If the document is encrypted and no (or a wrong) password is set, the `passwordrequest` event fires with `{ reason }`. Changing it reloads the document.
    */
   password?: unknown;
+  /**
+   * A reactive search query — the **controlled** alternative to the imperative `find()` handle. Setting it to a non-empty string scans every page, navigates to + coarse-highlights the first match, and emits `findresult` with the total occurrence count; clearing it (empty string / `null`) clears the highlight. Reactive so it works uniformly across all six targets (an Angular child-component `ref` cannot reach the `$expose` handle from a template event handler — the same reason `page` is a two-way model rather than a handle call).
+   */
+  query?: unknown;
   /**
    * Raw `getDocument` `DocumentInitParameters` passthrough — spread **before** the curated keys (explicit `src` / `password` win). For `cMapUrl`, `httpHeaders`, `withCredentials`, etc.
    */
@@ -81,7 +85,7 @@ export interface PdfViewerHandle {
 
 const PdfViewer = forwardRef<PdfViewerHandle, PdfViewerProps>(function PdfViewer(_props: PdfViewerProps, ref): JSX.Element {
   const __defaultOptions = useState(() => (() => ({}))())[0];
-  const props: Omit<PdfViewerProps, 'src' | 'scale' | 'rotation' | 'workerSrc' | 'standardFontDataUrl' | 'renderAllPages' | 'textLayer' | 'password' | 'options'> & { src: unknown; scale: number; rotation: number; workerSrc: string; standardFontDataUrl: string; renderAllPages: boolean; textLayer: boolean; password: unknown; options: Record<string, any> } = {
+  const props: Omit<PdfViewerProps, 'src' | 'scale' | 'rotation' | 'workerSrc' | 'standardFontDataUrl' | 'renderAllPages' | 'textLayer' | 'password' | 'query' | 'options'> & { src: unknown; scale: number; rotation: number; workerSrc: string; standardFontDataUrl: string; renderAllPages: boolean; textLayer: boolean; password: unknown; query: unknown; options: Record<string, any> } = {
     ..._props,
     src: _props.src ?? undefined,
     scale: _props.scale ?? 1,
@@ -91,11 +95,12 @@ const PdfViewer = forwardRef<PdfViewerHandle, PdfViewerProps>(function PdfViewer
     renderAllPages: _props.renderAllPages ?? false,
     textLayer: _props.textLayer ?? true,
     password: _props.password ?? undefined,
+    query: _props.query ?? undefined,
     options: _props.options ?? __defaultOptions,
   };
   const attrs: Record<string, unknown> = (() => {
-    const { src, page, scale, rotation, workerSrc, standardFontDataUrl, renderAllPages, textLayer, password, options, defaultValue, onPageChange, defaultPage, ...rest } = _props as PdfViewerProps & Record<string, unknown>;
-    void src; void page; void scale; void rotation; void workerSrc; void standardFontDataUrl; void renderAllPages; void textLayer; void password; void options; void defaultValue; void onPageChange; void defaultPage;
+    const { src, page, scale, rotation, workerSrc, standardFontDataUrl, renderAllPages, textLayer, password, query, options, defaultValue, onPageChange, defaultPage, ...rest } = _props as PdfViewerProps & Record<string, unknown>;
+    void src; void page; void scale; void rotation; void workerSrc; void standardFontDataUrl; void renderAllPages; void textLayer; void password; void query; void options; void defaultValue; void onPageChange; void defaultPage;
     return rest;
   })();
   const cancelled = useRef(false);
@@ -139,6 +144,7 @@ const PdfViewer = forwardRef<PdfViewerHandle, PdfViewerProps>(function PdfViewer
   const _watch9First = useRef(true);
   const _watch10First = useRef(true);
   const _watch11First = useRef(true);
+  const _watch12First = useRef(true);
 
   function buildSource() {
     let cfg: any = null;
@@ -602,6 +608,13 @@ const PdfViewer = forwardRef<PdfViewerHandle, PdfViewerProps>(function PdfViewer
     if (_watch11First.current) { _watch11First.current = false; return; }
     renderView();
   }, [props.textLayer]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    if (_watch12First.current) { _watch12First.current = false; return; }
+    const v = props.query;
+    if (v == null) return;
+    const q = String(v);
+    if (q) find(q);else clearFind();
+  }, [props.query]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const _rozieExposeRef = useRef({ getDocument, getPageCount, goToPage, nextPage, prevPage, setScale, zoomIn, zoomOut, fitWidth, fitPage, rotateCW, rotateCCW, download, getMetadata, getOutline, find, findNext, findPrev, clearFind });
   _rozieExposeRef.current = { getDocument, getPageCount, goToPage, nextPage, prevPage, setScale, zoomIn, zoomOut, fitWidth, fitPage, rotateCW, rotateCCW, download, getMetadata, getOutline, find, findNext, findPrev, clearFind };

packages/ui/pdf/packages/solid/README.md

@@ -46,6 +46,7 @@ export function Demo() {
 | `renderAllPages` | `Boolean` | `false` |  |  |
 | `textLayer` | `Boolean` | `true` |  |  |
 | `password` | `unknown` | `undefined` |  |  |
+| `query` | `unknown` | `undefined` |  |  |
 | `options` | `Object` | `{}` |  |  |
 
 ## Events