@aparte/plugin-artifacts 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aparté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @aparte/plugin-artifacts
+
+Artifacts for [aparté](https://github.com/apartejs/aparte): a document the model produces — a page, a
+component, a script, an SVG, a Markdown note, a spreadsheet — shown as a Code/Preview card in the
+transcript. An artifact is a convention an app teaches its model, not something a model does by
+nature, so the whole convention lives here: the `create_artifact` **tool** the model calls, the
+**card** that renders its result, and the `<artifact>` **tag grammar** for a model that writes one
+in its prose.
+
+```bash
+npm install @aparte/plugin-artifacts @aparte/core
+```
+
+```ts
+import { setupArtifacts } from '@aparte/plugin-artifacts';
+
+setupArtifacts(); // registers the tool, its renderer, the grammar and the segment renderer
+```
+
+`@aparte/core` is the only **peer dependency**.
+
+## Options
+
+```ts
+setupArtifacts({
+  name: 'create_artifact',        // the tool's name as the model sees it
+  systemPrompt: false,            // your own string, or false to send none
+  tag: 'artifact',                // the tag recognised in the prose; false for none
+  preview: true,                  // false: no Preview tab; a function: your own srcdoc builder
+  onBinary: async (artifact) => { // pdf / xlsx / docx: produce the file from the model's source
+    const { buffer, filename } = await runInYourSandbox(artifact.content);
+    return { buffer, filename, mime: artifact.mimeType };
+  },
+});
+```
+
+A second argument scopes everything to one `AparteConfig` instead of the global one. The call
+returns a function that unregisters all four.
+
+## What the card does
+
+- Opens on **Code**, highlighted through whatever highlighter core was given.
+- **Preview** — for `html`, `react`, `svg`, `js` and `css` — is mounted only when the reader
+  presses the tab: a previewable artifact is model-authored code, and mounting it unasked
+  executes it. The frame is `sandbox="allow-scripts"` with a CSP that lets nothing out.
+- **Copy** and **Download** on every text artifact; a binary one (`pdf`, `xlsx`, `docx`)
+  downloads only once your `onBinary` produced it — without one there is no button, because
+  the library holds no bytes.
+
+## Two ways in, one card
+
+A model with tools calls `create_artifact` with `{ mimeType, title, content }`; the handler
+returns the document as the tool's structured result and the card is drawn from it. A model
+without tools writes `<artifact type="text/html" title="…">…</artifact>` in its reply; core's
+parser — taught the grammar by this plugin through `registerStreamBlock` — streams it into an
+`artifact` segment the same card renders.
+
+MIME types follow the standard, plus Anthropic's `application/vnd.ant.*` namespace for
+framework kinds (`application/vnd.ant.react`). `deriveArtifactKind(mimeType)` gives the short
+kind the card switches on.

package/dist/binary-file.d.ts

@@ -0,0 +1,7 @@
+import type { ArtifactSegment } from './segment.js';
+/** For tests: forget every produced file and every generation in flight. */
+export declare function resetBinaryArtifacts(): void;
+export declare function renderBinaryFileArtifact(segment: ArtifactSegment, kind: string): string;
+export declare function setupBinaryFileArtifact(element: HTMLElement, segment: ArtifactSegment, kind: string): void;
+export declare function updateBinaryFileArtifact(element: HTMLElement, segment: ArtifactSegment, isStreaming: boolean): void;
+//# sourceMappingURL=binary-file.d.ts.map

package/dist/binary-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-file.d.ts","sourceRoot":"","sources":["../src/binary-file.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA8BpD,4EAA4E;AAC5E,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgEvF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAa1G;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAYnH"}

package/dist/card.d.ts

@@ -0,0 +1,6 @@
+import type { AparteSegmentRenderer } from '@aparte/core';
+import { type ArtifactSegment } from './segment.js';
+/** The segment shape the card draws — exported for a consumer's own tests and renderers. */
+export type AparteArtifactSegment = ArtifactSegment;
+export declare const artifactRenderer: AparteSegmentRenderer<ArtifactSegment>;
+//# sourceMappingURL=card.d.ts.map

package/dist/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAa3E,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAYpD,eAAO,MAAM,gBAAgB,EAAE,qBAAqB,CAAC,eAAe,CAoSnE,CAAC"}