# The artifacts kit — things made for review, every version kept, shown in a sandboxed viewer

> `Osysharp.Artifacts` keeps what somebody — often an agent — made for review on a row of your app: an HTML prototype, a picture, a PDF, a markdown note. Publishing under the same name again makes a new version and keeps every old one. People comment on one version, at a point of it if they like. The viewer shows a version in a frame the browser sandboxes twice, so an agent-made page runs its script in an origin of its own and can never act as your app.

<!-- id: ui-artifacts-kit · area: ui · stability: preview · html: https://osysharp.com/reference/ui/artifacts-kit/ -->

## Summary        {#summary}
An app where work is reviewed — a design, a report, a page an agent drafted — needs three things for what is reviewed:
it must be **kept** with every version, people must **comment** on a particular version, and it must be **shown safely**,
because a page somebody else wrote (an agent above all) must never run as your app inside the reviewer's session.

```osy syntax
app Studio {
  use Osysharp.Artifacts@0;
  use Osysharp.Storage;
  use Osysharp.Ui;
  model "model/**/*.osy";
}
```

## Signature      {#signature}
```osy syntax
using Osysharp.Artifacts;

// The app answers who — nobody, until it does.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => …;     // sees a subject's artifacts and comments
policy WritesArtifactsOf(string subjectType, Guid subjectId) => …;    // publishes on it
policy CommentsOnArtifactsOf(string subjectType, Guid subjectId) => …; // comments (readers, until the app says)

Artifact          PublishArtifact(string subjectType, Guid subjectId, string name, string contentType, byte[] bytes,
                                  Guid? delegation = null);   // new, or a new version under the same name
List<FileVersion> ArtifactVersions(Artifact artifact);        // every version, the first first
ArtifactComment   CommentOnArtifact(Artifact artifact, int version, string text, decimal? x = null, decimal? y = null);
void              ResolveArtifactComment(ArtifactComment comment, bool resolved = true);

ArtifactView(FileVersion version, int h = 640)                // one version, in the sandboxed frame
ArtifactFrame(version: Guid, title: string, <style props>)   // the atom ArtifactView draws
```

## Description    {#description}

### An artifact and its versions   {#versions}
An `Artifact` is on one row of the app — its **subject**, named by its type and id (`"Design"`, `design.Id`) — and holds
one `FileAsset`. Publishing under a name the subject already has calls `File.Supersede` on that file: the artifact is
the same row, the new content is the current version, and every earlier version stays, listed by `ArtifactVersions`
and viewable by `ArtifactView` ([A file's history — supersede, and what each version keeps](https://osysharp.com/reference/storage/file-versions/)). A new version keeps the artifact's type; publish another
type under a name of its own.

```osy syntax
var page = PublishArtifact("Design", design.Id, "index.html", "text/html", bytes, delegation: work.Id);
foreach (var v in ArtifactVersions(page)) {
  Text("version " + v.Version);
  ArtifactView(v, h: 480);
}
```

### What may be published   {#types}
`text/html`, `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/svg+xml`, `application/pdf`, `text/markdown`,
`text/plain` and `application/json`. The bytes are checked against the type: a "picture" that is really a page is
refused, and so is text that is not UTF-8. A version is at most 25 MB. An HTML prototype must be one self-contained
page; output of several files is several artifacts.

### The organisation's policy   {#org-policy}
`ArtifactsSetup` holds two settings an organisation's policy governs for every app it runs: `MaxBytes` (a `Range`: it
may lower the 25 MB cap) and `AllowPrototypes` (a `Lock`: it may forbid HTML prototypes outright). `PublishArtifact`
reads them on every upload, so the organisation's word holds whatever the app sets.

### Why the viewer is safe   {#sandbox}
Artifact bytes are served only by the platform's route `/_artifacts/{version}/{name}`, and every answer carries the CSP
`sandbox` directive. The browser then gives the document an **opaque origin, even when the address is opened directly
in a tab**: its script cannot read your app's cookies or storage, `connect-src 'none'` stops it calling your app or
anywhere else, and it may not submit forms, open windows or navigate. Only HTML may run script at all; a picture, a
PDF or a note is sandboxed with none. `ArtifactFrame` sets `sandbox="allow-scripts"` on the frame as well, so the
sandbox is set twice, and it takes no address and no sandbox setting from your code.

A frame's request carries no sign-in, so the viewer's address is **signed for the reader**: the platform reads the
artifact as them (`ReadsArtifactsOf`) and only then mints a short-lived address naming that one version. Somebody who
may not see it gets an empty frame, and the address without its signature answers nothing.

⚠ Chromium will not show a PDF inside a sandboxed frame. Show a PDF artifact with the PDF viewer kit, or offer it as a
download, rather than in `ArtifactView`.

### Comments   {#comments}
A comment is on one version — it stays with the version it was written on when a new one is published — and may name
a point of the frame (`x`, `y`, each a fraction from 0 to 1). It is live: a page listing a version's comments shows a
new one as it is written. `ResolveArtifactComment` marks it done.

## Examples       {#examples}

### A design's prototypes, each shown sandboxed   {#example-history}
```osy title="the artifacts on a design, in their sandboxed viewer" test app=ui-artifacts-kit
app Studio {
  use Osysharp.Artifacts@0;
  use Osysharp.Storage;
  use Osysharp.Ui;
  model "model/**/*.osy";
}

using Osysharp.Ui;
using Osysharp.Artifacts;

entity Design {
  [Required, MaxLength(80)] string Title;
  security { allow read when IsAuthenticated; }
}

// Whoever may read a design sees its artifacts and publishes on it.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => subjectType == "Design" && Design.Any(d => d.Id == subjectId);
policy WritesArtifactsOf(string subjectType, Guid subjectId) => ReadsArtifactsOf(subjectType, subjectId);

[Route("/designs/{id}/artifacts")]
component DesignArtifacts(Guid id) {
  render {
    Stack(gap: 2) {
      foreach (var a in Artifact.Where(x => x.SubjectType == "Design" && x.SubjectId == id).Include(x => x.File.CurrentVersion).ToList()) {
        Text(a.Name);
        ArtifactView(a.File.CurrentVersion, h: 720);
      }
    }
  }
}
```

## Traps that cost real time   {#traps}
**The subject is two values, not a reference.** An artifact can be on any row of any type, so it names it by type and
id. Your policies decide what each pair means; a pair no policy admits is nobody's.

**`Frame(html)` is not this.** `Frame` shows a document with no script at all ([Frame](https://osysharp.com/reference/ui/frame/)), which is what a mail
preview wants. A prototype needs its script, which is why it has a viewer of its own.

## See also       {#see-also}
- [A file's history — supersede, and what each version keeps](https://osysharp.com/reference/storage/file-versions/) — a file's history: what each version keeps, and `File.Supersede`
- [Frame](https://osysharp.com/reference/ui/frame/) — a whole document in a frame with no script at all, for a mail preview
