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

openplanr artifact ./artifact.html
openplanr artifact open /absolute/path/to/artifact.html --theme auto
openplanr artifact open ./artifact.html --presentation canvas
openplanr artifact export <session-id> --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

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/<slug>/<slug>.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/<id> 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

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.<payload>. 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:

openplanr artifact import "<review-url>" "<second-review-url>"

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/<artifact-id>/ 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.