@rasterex/viewer 1.1.0 → 1.1.1

package/README.md

@@ -1,43 +1,73 @@
 # Rasterex Viewer SDK
 
-Embed Rasterex Canvas in your web application with the Rasterex Viewer SDK: a
-small, framework-independent TypeScript SDK that uses an iframe and
-PostMessage.
+Embed Rasterex Canvas in a web application with a small, framework-independent
+TypeScript SDK. The SDK mounts Canvas in an iframe, communicates through
+PostMessage, and provides typed APIs for files, tools, events, and viewer
+features.
 
-Customer production deployments are self-hosted. Rasterex provides hosted
-Canvas for evaluation and proof-of-concept testing.
-
-The SDK mounts the viewer, opens files, controls tools, listens for viewer events, and provides TypeScript types for the public API.
+Customer production deployments are self-hosted. Rasterex provides a hosted
+Canvas Sandbox for evaluation and proof-of-concept testing.
 
 Full [documentation](https://docs.rasterex.com/) ·
 [source](https://github.com/Rasterex-Software/rasterex-viewer) ·
 [runnable examples](https://github.com/Rasterex-Software/rasterex-viewer-examples) ·
 [issues and support](https://github.com/Rasterex-Software/rasterex-viewer/issues)
 
-## Install
+## Choose A Viewer Environment
 
-```sh
-npm install @rasterex/viewer
+### Hosted Sandbox
+
+The SDK defaults to `https://sandbox.rasterex.com`, Rasterex's hosted Canvas
+environment for evaluation and proof-of-concept testing. The SDK embeds it in
+an iframe and sends Canvas broker messages to that origin.
+
+Documents opened in Sandbox must be reachable from the hosted viewer
+environment. The public PDF used in the examples is intentionally suitable for
+this purpose.
+
+### Self-Hosted Production
+
+Do not treat the hosted Sandbox as a customer production deployment. For
+production, private files, or network-restricted content, deploy Rasterex
+Canvas in your own environment and provide its URL:
+
+```ts
+import { createViewer } from "@rasterex/viewer";
+
+const viewer = createViewer({
+  container: "#rx-viewer",
+  viewerUrl: "https://viewer.example.com",
+  targetOrigin: "https://viewer.example.com"
+});
+
+await viewer.mount();
+await viewer.ready();
 ```
 
-## Requirements
+If `targetOrigin` is omitted, the SDK derives it from `viewerUrl` with
+`new URL(viewerUrl).origin`.
 
-Use the package from a bundled application such as Vite, Next.js, Angular, React, Vue, Webpack, or Rollup.
+## Install And Requirements
 
-Use Node.js `^20.19.0 || >=22.12.0` when developing, building, or releasing
-this package.
+```sh
+npm install @rasterex/viewer
+```
 
-Browsers cannot resolve npm package names directly from a plain `<script type="module">` file without a bundler or import map.
+Use the package from a bundled application such as Vite, Next.js, Angular,
+React, Vue, Webpack, or Rollup. Use Node.js `^20.19.0 || >=22.12.0` when
+developing, building, or releasing this package.
 
-The viewer container must have a real width and height before mounting.
+The viewer container must have a real width and height before mounting:
 
 ```html
 <div id="rx-viewer" style="width: 100%; height: 640px"></div>
 ```
 
-## No Framework
+### Plain HTML Without A Bundler
 
-For a plain HTML page without a framework or bundler, install the package and add an import map before your module script.
+Browsers cannot resolve npm package names directly from a plain
+`<script type="module">` without a bundler or import map. Install the package
+and add an import map before your module script:
 
 ```html
 <div id="rx-viewer" style="width: 100%; height: 640px"></div>
@@ -54,9 +84,7 @@ For a plain HTML page without a framework or bundler, install the package and ad
 <script type="module">
   import { createViewer } from "@rasterex/viewer";
 
-  const viewer = createViewer({
-    container: "#rx-viewer"
-  });
+  const viewer = createViewer({ container: "#rx-viewer" });
 
   await viewer.mount();
   await viewer.ready();
@@ -65,6 +93,8 @@ For a plain HTML page without a framework or bundler, install the package and ad
 
 ## Quick Start
 
+Create a viewer, mount its iframe, then wait for Canvas to become ready:
+
 ```ts
 import { createViewer } from "@rasterex/viewer";
 
@@ -76,39 +106,34 @@ await viewer.mount();
 await viewer.ready();
 ```
 
-By default, the SDK loads Rasterex's hosted Canvas environment for evaluation
-and proof-of-concept testing:
+Without `viewerUrl`, this uses the hosted Sandbox. `targetOrigin` is derived
+from the viewer URL when it is not provided.
 
-```txt
-https://sandbox.rasterex.com
-```
+## Open A Document
 
-`targetOrigin` is derived from the viewer URL when it is not provided.
-
-For customer production deployments, set `viewerUrl` to your self-hosted
-Rasterex Canvas URL.
-
-## Open A File URL
+After the viewer is ready, open a document URL:
 
 ```ts
 await viewer.documents.open({
-  url: "https://pdfobject.com/pdf/sample.pdf",
+  url: "https://res.cloudinary.com/dvgeew3bj/image/upload/v1779169700/Main_version_1.pdf_1_ifrgjq.pdf",
   displayName: "sample.pdf",
   cacheId: "file_7f3a9c2_sample_pdf",
   mime: "application/pdf"
 });
 ```
 
-The file URL must be reachable by the viewer environment.
+The file URL must be reachable by the viewer environment. This example uses a
+public PDF for Sandbox demonstration only; production URLs must be reachable
+by your self-hosted Rasterex Canvas deployment.
 
-This example uses a public PDF for demonstration only. In production, provide
-a file URL that is reachable by your self-hosted Rasterex Canvas deployment.
+`displayName` should include the file extension, such as `sample.pdf`.
+`cacheId` should be a stable file or content ID from your application or server,
+not the display name. It lets the server reuse already processed content for the
+same file, which can make repeat opens faster.
 
-`displayName` should include the file extension, for example `sample.pdf`.
+### Create, Mount, And Open In One Call
 
-`cacheId` should be a stable file/content ID from your application or server, not the display file name. It lets the server reuse already processed content for the same file, which can make repeat opens faster.
-
-## Mount And Open In One Call
+Use `createDocumentViewer` when the first action should be opening a document:
 
 ```ts
 import { createDocumentViewer } from "@rasterex/viewer";
@@ -116,56 +141,13 @@ import { createDocumentViewer } from "@rasterex/viewer";
 const viewer = await createDocumentViewer({
   container: "#rx-viewer",
   document: {
-    url: "https://pdfobject.com/pdf/sample.pdf",
+    url: "https://res.cloudinary.com/dvgeew3bj/image/upload/v1779169700/Main_version_1.pdf_1_ifrgjq.pdf",
     displayName: "sample.pdf"
   }
 });
 ```
 
-## Custom Viewer URL
-
-For customer production deployments, use `viewerUrl` for your self-hosted
-Rasterex Canvas URL. The default hosted Canvas environment is intended for
-evaluation and proof-of-concept testing.
-
-```ts
-import { createViewer } from "@rasterex/viewer";
-
-const viewer = createViewer({
-  container: "#rx-viewer",
-  viewerUrl: "https://viewer.example.com",
-  targetOrigin: "https://viewer.example.com"
-});
-
-await viewer.mount();
-await viewer.ready();
-```
-
-If `targetOrigin` is omitted, the SDK uses `new URL(viewerUrl).origin`.
-
-## Tools
-
-```ts
-await viewer.tools.set({
-  group: "measurement",
-  action: "MEASURE_LENGTH",
-  enabled: true
-});
-
-viewer.tools.clear();
-```
-
-## Annotation Events
-
-```ts
-const unsubscribe = viewer.annotations.on("created", (event) => {
-  console.log(event.guid, event.data);
-});
-
-unsubscribe();
-```
-
-## Options
+## Configuration
 
 ```ts
 interface RasterexViewerOptions {
@@ -195,38 +177,6 @@ interface RasterexViewerOptions {
 | `iframeClassName` | CSS class applied to the iframe. |
 | `iframeAttributes` | Extra iframe attributes, for example `{ allow: "fullscreen" }`. |
 
-## Presets
-
-Presets are optional and are exported from a separate entrypoint.
-
-```ts
-import { createViewer } from "@rasterex/viewer";
-import { sandboxCanvas, takeoffDemo } from "@rasterex/viewer/demo-presets";
-
-const viewer = createViewer({
-  container: "#rx-viewer",
-  viewerUrl: sandboxCanvas.viewerUrl,
-  targetOrigin: sandboxCanvas.targetOrigin
-});
-```
-
-Takeoff is not loaded by default. Use `takeoffDemo` only when your app explicitly chooses that preset.
-
-## TypeScript
-
-Types are included.
-
-```ts
-import type {
-  DocumentOpenOptions,
-  RasterexViewerOptions,
-  ToolAction,
-  ToolGroup
-} from "@rasterex/viewer";
-```
-
-TypeScript will report invalid option names, unsupported tool actions, and wrong payload shapes at compile time.
-
 ## Common APIs
 
 ```ts
@@ -234,35 +184,88 @@ await viewer.documents.open({ url: "/files/sample.pdf", displayName: "sample.pdf
 await viewer.tools.set({ group: "measurement", action: "MEASURE_LENGTH", enabled: true });
 viewer.tools.clear();
 viewer.annotations.select({ guid: "annotation-guid" });
+
 const snapshot = await viewer.layers.getLayers();
 const firstLayer = snapshot.layers[0];
 if (firstLayer?.index !== undefined) {
   await viewer.layers.setLayerVisibility({ index: firstLayer.index, visible: false });
 }
+
 const blocks = await viewer.blocks.getBlocks();
 const firstBlock = blocks.blocks[0];
 if (firstBlock?.index !== undefined) {
   await viewer.blocks.getBlockDetails({ index: firstBlock.index });
   viewer.blocks.setBlockVisibility({ index: firstBlock.index, visible: false });
 }
+
 viewer.compare.compare({ backgroundUrl: "old.pdf", overlayUrl: "new.pdf" });
 viewer.styles.setGlobalAppearance({ strokeColor: "#164863" });
 viewer.diagnostics.on("transport.error", (event) => console.error(event.error));
 ```
 
-## Cleanup
+### Tool Control
+
+```ts
+await viewer.tools.set({
+  group: "measurement",
+  action: "MEASURE_LENGTH",
+  enabled: true
+});
+
+viewer.tools.clear();
+```
 
-Destroy the viewer when the page, route, or component no longer needs it.
+### Annotation Events
 
 ```ts
-viewer.destroy();
+const unsubscribe = viewer.annotations.on("created", (event) => {
+  console.log(event.guid, event.data);
+});
+
+unsubscribe();
 ```
 
-## License
+## TypeScript
 
-This npm SDK is licensed under the MIT License.
+Types are included with the package:
+
+```ts
+import type {
+  DocumentOpenOptions,
+  RasterexViewerOptions,
+  ToolAction,
+  ToolGroup
+} from "@rasterex/viewer";
+```
+
+TypeScript reports invalid option names, unsupported tool actions, and invalid
+payload shapes at compile time.
+
+## Optional Demo Presets
+
+Hosted presets are exported from a separate entrypoint:
+
+```ts
+import { createViewer } from "@rasterex/viewer";
+import { sandboxCanvas, takeoffDemo } from "@rasterex/viewer/demo-presets";
 
-The SDK embeds Rasterex Canvas/viewer deployments through an iframe. The Rasterex Canvas application, hosted services, server components, viewer assets, and customer deployments are not licensed by this SDK package and remain subject to their own licenses and agreements.
+const viewer = createViewer({
+  container: "#rx-viewer",
+  viewerUrl: sandboxCanvas.viewerUrl,
+  targetOrigin: sandboxCanvas.targetOrigin
+});
+```
+
+Takeoff is not loaded by default. Use `takeoffDemo` only when your application
+explicitly selects that preset.
+
+## Cleanup
+
+Destroy the viewer when the page, route, or component no longer needs it:
+
+```ts
+viewer.destroy();
+```
 
 ## Supply Chain Security
 
@@ -283,6 +286,14 @@ npm pack --json
 ```
 
 Install the generated tarball in a clean project and verify the public package
-imports before publishing.
+imports before publishing. See `SECURITY.md` for the vulnerability reporting
+policy and package security scope.
+
+## License
+
+This npm SDK is licensed under the MIT License.
 
-See `SECURITY.md` for the vulnerability reporting policy and package security scope.
+The SDK embeds Rasterex Canvas/viewer deployments through an iframe. The
+Rasterex Canvas application, hosted services, server components, viewer assets,
+and customer deployments are not licensed by this SDK package and remain
+subject to their own licenses and agreements.

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "1.1.0";
+export declare const SDK_VERSION = "1.1.1";
 export declare const DEFAULT_VIEWER_URL = "https://sandbox.rasterex.com";
 export declare const DEFAULT_TARGET_ORIGIN = "https://sandbox.rasterex.com";
 export declare const DEFAULT_IFRAME_TITLE = "Rasterex Viewer";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "1.1.0";
+export const SDK_VERSION = "1.1.1";
 export const DEFAULT_VIEWER_URL = "https://sandbox.rasterex.com";
 export const DEFAULT_TARGET_ORIGIN = "https://sandbox.rasterex.com";
 export const DEFAULT_IFRAME_TITLE = "Rasterex Viewer";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasterex/viewer",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "TypeScript SDK for embedding Rasterex Canvas in web applications via iframe and PostMessage. Built for customer self-hosted deployments; hosted Canvas is available for evaluation and proof-of-concept testing.",
   "author": {
     "name": "Rasterex Software AS",