@artorapp/web-sdk

The Artor in-page review widget. Drop it into your prototype and reviewers can leave element-anchored comments directly on the running page when it's served from an Artor preview origin.

It self-disables everywhere else — init() is a silent no-op on localhost or any production host, so it's safe to leave committed. The bundle is self-contained (Preact is bundled in); it has no runtime dependencies and adds nothing to your app off-preview.

Install

npm i @artorapp/web-sdk

artor init adds and wires this automatically on first link for common web frameworks. The steps below are for manual setup.

Usage

import { init } from "@artorapp/web-sdk";

// Idempotent; returns a teardown handle. No-op off the Artor preview origin.
if (typeof window !== "undefined") init();

React (run once on mount):

import { useEffect } from "react";
import { init } from "@artorapp/web-sdk";

export function ArtorReview() {
  useEffect(() => init().teardown, []);
  return null;
}

Demo mode (marketing/demo pages)

init({ demo: true }) mounts the widget even off a preview origin — for a marketing or demo page that wants the real review UI without an Artor backend. In this mode the caller owns the backend: pass a fetchImpl that serves the review API (/__dn_review/session, /comments, /reply, /resolve, …) from whatever store you like (e.g. localStorage). Without a working fetchImpl the widget fails closed and stays hidden, same as any backend outage.

init({ demo: true, fetchImpl: myLocalStorageReviewApi });

A prebuilt IIFE global build is also published for script-tag use. Pin an exact version and add Subresource Integrity in production (get the sha384 hash from the published file):

<script
  src="https://unpkg.com/@artorapp/[email protected]/dist/index.global.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>
<script>
  ArtorWebSdk.init();
</script>

API

init(opts?: { fetchImpl?: typeof fetch }): { teardown: () => void } — mounts the widget on the Artor preview origin (no-op elsewhere). Calling it twice is a no-op; teardown() removes every listener, observer, and DOM node it created.

Local development

web-sdk/playground/ is a permanent dev harness for iterating on the widget's UI without a real Artor server, an org, or a published preview. Run it with:

pnpm --filter @artorapp/web-sdk play

This starts Vite against playground/index.html: a small sample page (nav, hero, pricing cards, a contact form, a long prose paragraph for text-selection testing, an activity table, a modal-ish panel, and a custom element with an open shadow root) with the widget mounted via buildWidget against an in-memory mock client (playground/mock-client.ts) instead of the real /__dn_review/* HTTP API — so the playground never talks to a server and needs no auth, org, or deployment.

A floating switcher panel (top-left) lets you drive the widget through its states live:

• Widget state — full / readonly / signedout / pending / hidden, mapping to the same widgetState values the real session response produces.
• Sample data — five seed sets (few, many, resolved, pinned — threads anchored to real elements on the page, parked — threads whose elementSelector no longer resolves to any element, including one seeded aiIgnored: true to see the "AI: off" badge) that re-seed the mock client and reload the current route's threads.
• Fail next members() call / Fail next write — toggle/trigger the mock client into returning an error on the next roster fetch or comment/resolve write, to exercise the widget's error states without a real network failure.

The playground is never published: web-sdk/package.json's files field is ["dist", "README.md", "LICENSE"], and src/build.test.ts asserts that array exactly — so an npm pack/npm publish tarball can never pick up playground/ even by accident.

License

Proprietary — © 2026 Artor. All rights reserved. See LICENSE.