--- title: Artifact review and private sharing description: openplanr artifact opens native diagrams, authored designs, and HTML artifacts for local review or explicit encrypted sharing. url: https://openplanr.dev/docs/guides/artifact-review updated: 2026-10-06 related: - https://openplanr.dev/docs/guides/review.md --- # Artifact review and private sharing `openplanr artifact` opens native diagrams, authored designs, and HTML artifacts for local review or explicit encrypted sharing. Generic HTML sessions support comments, pins, threads, and Approve or Request changes decisions. JavaScript inside the artifact remains interactive in an opaque-origin, network-blocked sandbox. Generic artifacts open in `document` presentation by default: the complete artifact is the edge-to-edge page with a compact floating comments rail. The prior zoomable artboard is still available as `canvas` presentation and remains the default for design boards and multi-variant workflows. ## Local review ```bash openplanr artifact ./artifact.html openplanr artifact open /absolute/path/to/artifact.html --theme auto openplanr artifact open ./artifact.html --presentation canvas openplanr artifact export --format markdown --output review.md ``` The bundler packages local CSS, scripts, modules, images, SVG, fonts, `srcset`, and CSS `url()` references. With no `--root`, the artifact's own directory is the dependency root, so absolute files from Downloads or another project work without extra flags. It also vendors safe public HTTPS dependency graphs (such as Google Fonts, CDN stylesheets, scripts, images, and fonts) into the immutable artifact before review or sharing. Forms, traversal, symlink escapes, unsafe or unavailable remote assets, and unresolved dependencies remain rejected. Use `--no-open --json` for remote or SSH sessions, then forward the printed loopback port explicitly. `--presentation auto|document|canvas` is available on `open` and `share`. `auto` resolves one generic artifact to `document`; explicit overrides win. Document feedback starts closed and opens as an overlay without resizing the artifact. JSON output includes the resolved presentation. The complete local HTML/CSS/JavaScript graph is bundled into immutable bytes before review or sharing. The viewer does not fetch the original project after sharing. It loads those bytes through an invisible Blob iframe with `sandbox="allow-scripts"`; it never injects artifact HTML into OpenPlanr or executes it under the `share.openplanr.dev` origin. A bounded authenticated layout bridge provides natural outer-page scrolling and full-document pins. This is private artifact review, not standalone website hosting. Publishing a top-level website would require a separate isolated artifact origin and is not part of this command. ## Native diagram sharing ```bash openplanr artifact open ./diagrams/handover/handover.manifest.json openplanr artifact share ./diagrams/handover/handover.manifest.json --yes --no-open openplanr artifact publish ./diagrams/handover/handover.manifest.json --yes openplanr artifact sync ./diagrams/handover/handover.manifest.json ``` An authored `diagrams//.planr-diagram-bundle.json` is also accepted. Sharing publishes the selected diagram's native scene without converting its format or rerunning layout. The creation preview shows its title, source revision, publication contents, destination and retention. Original source bytes, local paths and private provenance are excluded. Each diagram has a stable `/diagram/` URL and a separate reviewer access token. Use the local studio's **Share diagram** dialog to copy them separately. Owner custody is kept privately outside the repository. Ordinary command output contains no tokens or signing keys; `--secret-output` explicitly exports recovery to a new private file. Reviews last until revoked or deleted and remain available while the owner's laptop is offline. Local edits remain unpublished until **Publish revision** or `artifact publish`. Comments are tied to their published revision and element or scene position. Earlier revisions stay readable but accept no new comments. Synchronization imports feedback into the local ledger without modifying diagram content. Reviewers can use outline/search, inspection, pan/zoom, Fit, Present, Discussion, Revisions, and SVG/PNG or feedback export. The native shell loads its packaged font before reporting readiness and preserves wide diagrams without an HTML wrapper viewport. An incompatible installed runtime or hosted service produces a compatibility error. There is no automatic HTML fallback. To share an HTML snapshot, export HTML first and explicitly use the generic snapshot route. ## Private links ```bash openplanr artifact share ./artifact.html --secret-output ./room.private.json openplanr artifact share ./artifact.html --presentation document --secret-output ./room.private.json openplanr artifact share ./artifact.html --snapshot --short --ttl 7d --yes ``` By default, sharing creates one stable encrypted live review room. The normal review URL lets anyone with the link view and comment. A distinct owner-verdict URL plus the matching private P-256 signer can approve or request changes. The management URL can only pause/reopen comments or delete the room. The required `--secret-output` path is reserved exclusively, then an exact recovery bundle containing all three URLs and the owner signer is made durable at mode 0600 before the first room request. A lost response is retried once with the same prepared room identity, ciphertext, and capabilities, so it cannot create a duplicate or rotate the recovery URLs. A validated no-effect rejection revokes the bundle; an ambiguous outcome preserves it and returns a bounded, path-free recovery error. New feedback synchronizes to other open review tabs immediately. The artifact itself remains immutable and the service never receives the private signer. Use `--snapshot` for the immutable sharing model. Artifacts whose encoded fragments are 8,000 characters or less use `https://share.openplanr.dev/#v1.`. The browser fragment is not sent in the HTTP request, so the host receives no artifact content. Fragment links are encoded, not encrypted: anyone who receives the URL can read the review. Larger artifacts require an explicit encrypted short-link upload. OpenPlanr compresses the envelope, encrypts it with AES-256-GCM, uploads ciphertext, and puts the key only after `#k=` in the URL. The service sees request metadata and ciphertext, never plaintext or the key. Links are immutable and expire after 1, 7, or 30 days. Save the one-time deletion token when it is displayed. ## Return and import feedback Live-room feedback stays in its encrypted room until expiry or deletion. Import the room URL at any point to merge its latest full feedback state locally. For snapshot sharing, a reviewer still returns a new immutable review URL. Import one or more room or snapshot URLs non-destructively: ```bash openplanr artifact import "" "" ``` Changed-artifact feedback is rejected with `E_ARTIFACT_STALE_REVIEW`. To retain it for audit, rerun with `--allow-stale`, inspect the digest and feedback-count preview, and confirm. Automation must use `--allow-stale --yes`. Generic review state is stored in `.planr/artifacts//` inside a valid project and under `~/.planr/artifacts/` elsewhere. Design-board reviews continue to merge into the adjacent `feedback.json` contract. ## Minimal installs, offline use, and self-hosting A planning-only installation returns `E_PIPELINE_NOT_INSTALLED`; install the full distribution with `npm install -g openplanr@latest`. Local review and export work offline after installation. Creating or opening a remote review link requires network access. The shell assets and Protocol v1.1 schemas are shipped by `planr-pipeline`. Self-hosters can point `OPENPLANR_SHARE_BASE` at their own HTTPS origin serving the static viewer and share Worker.