@embedpdf/plugin-stage 3.0.0-next.0

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

@@ -0,0 +1,205 @@
+# @embedpdf/plugin-stage
+
+The Stage is the viewer's coordinate system: it lays pages out into a scene,
+points a camera at them, and turns every scroll, zoom, resize, and "go to page 5"
+into one camera move. Everything you see is the camera; everything you configure
+is a policy about how the camera is allowed to move.
+
+## The camera: one mental model
+
+**Every camera move is defined by what it holds fixed.** There are five kinds of
+move, and each one keeps exactly one thing still:
+
+| You do…                                            | What stays fixed               | Controlled by                 |
+| -------------------------------------------------- | ------------------------------ | ----------------------------- |
+| drag, pinch, ctrl+wheel                            | the content under your pointer | nothing — that's physics      |
+| click zoom in/out, `zoomTo`, switch to fit-width   | a focal point in the viewport  | **`zoomAlign`**               |
+| resize the container, rotate a page, change spread | the spot you were looking at   | **`anchorAlign`**             |
+| `goToPage`, next/prev, reset                       | nothing — a fresh landing      | **`arrivalAlign`**            |
+| click an outline entry, a search hit, a PDF link   | whatever the call specifies    | the call itself, per-`reveal` |
+
+One more setting stands outside the table. When an axis of content **fits** the
+viewport, the camera has no freedom on that axis — there is nowhere to scroll.
+**`fitAlign`** says where content rests in that case (default: centered). It is a
+standing constraint applied to _every_ move above, not a move of its own.
+
+All four settings speak the same per-axis vocabulary, and `x`/`y` are independent:
+
+```ts
+stagePlugin({
+  arrivalAlign: { x: 'start', y: 'start' },
+  zoomAlign: { x: 'center', y: 'center' },
+  anchorAlign: { x: 'start', y: 'start' },
+  fitAlign: { x: 'center', y: 'center' },
+});
+```
+
+(The values above are the defaults — a document-reading feel. If that's what you
+want, configure nothing.)
+
+## `arrivalAlign` — where navigation lands
+
+When you _navigate_ (`goToPage`, `next`, `prev`, reset), the target page lands at
+the same place **at every zoom level** — landing is a policy, never a side effect
+of how zoomed in you happen to be. Per axis:
+
+| Value      | Landing                                                                   |
+| ---------- | ------------------------------------------------------------------------- |
+| `'start'`  | reading edge flush with the viewport edge (top / reading-start) — default |
+| `'center'` | page centered — the presentation feel                                     |
+| `'end'`    | far edge flush                                                            |
+| `0`–`1`    | page center at this viewport fraction (`0.35` ≈ a browser find-bar)       |
+| `'keep'`   | this axis doesn't move at all                                             |
+
+Landings clamp against the document edges, so they are best-effort on the first
+and last pages — exactly like a browser.
+
+One value deserves a second look: **`x: 'keep'`** — page forward without losing
+your horizontal position. Zoomed into the left column of a two-column paper,
+`next()` takes you to the left column of the next page. (It's the PDF
+`/XYZ null` semantic, as a default.)
+
+Any single navigation can override the setting:
+
+```ts
+stage.goToPage(12, { arrivalAlign: { y: 'center' } });
+```
+
+## `zoomAlign` — what focal-less zoom zooms around
+
+Pinch and ctrl+wheel always zoom around the pointer — that is not configurable,
+because anything else feels broken. `zoomAlign` answers the remaining case:
+zooming with **no pointer position** — toolbar buttons, keyboard shortcuts,
+`zoomTo`, switching between fit modes.
+
+Default `{ x: 'center', y: 'center' }`: the middle of what you see stays put and
+the view inflates around it. Set `y: 'start'` for top-stable zoom — the first
+visible line holds still while everything grows below it (the text-editor feel).
+Values: `'start' | 'center' | 'end' |` fraction.
+
+## `anchorAlign` — what survives a reframe
+
+When the world reshapes under a passive camera — the container resizes, a page is
+rotated or deleted, the gap or spread changes — the Stage keeps you looking at
+what you were looking at. `anchorAlign` says **where in the viewport** that
+reference point lives: it is captured there before the change and restored there
+after.
+
+Default `{ x: 'start', y: 'start' }` — the browser scroll model: the top of what
+you see is pinned, and growth or shrinkage happens below. This is why a container
+that mounts small and then expands doesn't shove the document downward: the top
+stays where it was and the extra height reveals more page.
+
+Set `{ x: 'center', y: 'center' }` for canvas-style reframes: the middle is
+pinned and resizes balloon symmetrically (the Figma feel).
+
+## `viewRotation` — rotate the view, not the document
+
+Adobe's "Rotate View": a quarter-turn applied to how **every page displays in
+this lens**, on top of each page's own `/Rotate`.
+
+```ts
+stage.rotateView(90); // toolbar verb: one quarter-turn clockwise from here
+stage.setViewRotation(180); // absolute
+stage.viewRotation(); // 0 | 90 | 180 | 270
+stagePlugin({ viewRotation: 90 }); // or start rotated
+```
+
+Three properties define it:
+
+- **Non-persistent.** Nothing is written to the PDF — no engine call, no
+  registry revision. Saving the document saves what was loaded. The permanent
+  per-page rotation is `plugin-page-edit`'s `rotateBy`/`setRotation`; keep the
+  two on different buttons.
+- **Per lens.** It is a `StageSettings` field like `zoom` or `layout`, so the
+  main viewer rotates while a thumbnail lens stays upright — or share one
+  setting across lenses if your product wants them to agree.
+- **A reframe.** Changing it holds the `anchorAlign` point like any other
+  scene change (the "rotate a page" row in the table above), and fit-modes
+  re-resolve against the swapped footprint.
+
+Annotation tools that place content with a reading orientation (stamp,
+free-text) counter-rotate against the **total** display rotation — `/Rotate` +
+`viewRotation` — via their `upright` option, so what the author places reads
+horizontally exactly as they see it.
+
+## Recipes
+
+**Document reading** — the defaults. Configure nothing.
+
+**Presentation / construction sheets** — every move keeps the current sheet
+centered; each arrival presents the sheet like a slide:
+
+```ts
+stagePlugin({
+  arrivalAlign: { x: 'center', y: 'center' },
+  zoomAlign: { x: 'center', y: 'center' },
+  anchorAlign: { x: 'center', y: 'center' },
+});
+```
+
+**Zoomed-in reading of scanned two-column papers** — hold the column while
+paging, land a comfortable third from the top:
+
+```ts
+stagePlugin({ arrivalAlign: { x: 'keep', y: 0.35 } });
+```
+
+A "preset" is just an object you keep and pass — to `stagePlugin()` at setup or
+`stage.update()` at runtime. The plugin ships no named presets; that taxonomy
+belongs to your product.
+
+## The scroller contract — scrollbars, minimaps, "% read"
+
+The Stage doubles as a **virtual scroll element**. `scrollMetrics()` projects
+the camera into the native DOM vocabulary — every field means exactly what it
+means on a `<div>`, in screen px:
+
+```ts
+const m = stage.scrollMetrics();
+// m.scrollTop / m.scrollLeft       — where you are
+// m.scrollHeight / m.scrollWidth   — how much there is
+// m.clientHeight / m.clientWidth   — how much you see
+// m.scrollableY / m.scrollableX    — false = nothing to scroll (hide the bar)
+
+stage.scrollTo({ top: 0 }); // Element.scrollTo semantics
+stage.scrollBy({ top: m.clientHeight * 0.9 }); // page down
+```
+
+That is the whole contract. A scrollbar thumb is
+`clientHeight / scrollHeight` of the track, positioned at
+`scrollTop / scrollHeight`; a reading-progress indicator is
+`scrollTop / (scrollHeight − clientHeight)`; a minimap is the same numbers
+drawn small. You never touch camera math.
+
+The metrics are derived from the **same travel range the pan clamp uses**, so
+a scrollbar can never disagree with where panning actually stops:
+
+- **Zoom** reshapes the range live — zoom in and the thumb shrinks, exactly
+  like a longer document.
+- **Paged flow** scrolls the current item: the bar reflects one page (or
+  spread), and hides when it fits.
+- **A fitting axis** reports `scrollable: false` with `scrollWidth ===
+clientWidth` — the native "no bar" condition, for free.
+- **RTL** stays physical: `scrollLeft` is the offset from the range's left
+  edge, deliberately sidestepping the DOM's negative-`scrollLeft` behavior.
+
+**Unbounded stages get the Figma scrollbar.** With `bounded: false` the range
+is the union of the content and your current view: pan off into empty canvas
+and `scrollHeight` grows, the thumb shrinking toward the edge — but dragging
+it to the other end always rides you back across the content. When everything
+is in view, both axes report unscrollable and the bars disappear.
+
+`scrollTo`/`scrollBy` default to `behavior: 'instant'` (the DOM's `'auto'`);
+pass `'smooth'` for the camera tween. The `scrollBehavior` _setting_ is not
+consulted — it governs navigation verbs (`goToPage`, `next`), not scrolling.
+
+## What these settings never touch
+
+- **Gestures.** Pan and pinch hold the pointer. Physics, not policy.
+- **Explicit arrivals.** `reveal(page, { rect, zoom, anchor })` — search hits,
+  outline clicks, PDF destinations — carries its own anchor and always beats the
+  settings. Bare `reveal(page)` stays minimal-movement: it scrolls only as far as
+  needed to make the page visible, and not a pixel further.
+- **Saved viewpoints.** `goToPage(i, { viewpoint })` restores exactly what was
+  captured.