Portable artifacts

Artifacts let an AI client save a small, durable page in your Stackyapper workspace. Stackyapper hosts the page, keeps immutable revisions, and applies the current viewer's permissions every time a control runs.

Artifact hosting is a beta, currently limited to allowlisted Business workspaces. If a workspace leaves Business, artifact owners retain an owner-only catalog for opening, exporting, and deleting their existing artifacts. Creating, editing, sharing, importing, running controls, and AI client discovery remain unavailable until Business is active again.

Delivery and compatibility

Client capability	What opens
MCP Apps with `text/html;profile=mcp-app`	An embedded, network-isolated hosted page
MCP without that capability	An authenticated Stackyapper portal link
Export/import only	A `stackyapper.artifact/v1` backup package

The fallback link is part of the protocol contract: a client never needs to execute HTML or JavaScript to preserve or reopen an artifact. Support can vary by client version and admin policy.

Editing across clients

Authorized AI clients can manage an artifact's lifecycle through Stackyapper: load metadata, read the source in bounded chunks, list revisions, and submit a replacement source document. Claude and ChatGPT are tested with the beta; other clients that follow the protocol should work but are not verified end to end.

Every update names the revision it started from. If another client has already saved a newer revision, Stackyapper rejects the stale update and tells the client to reload and merge — safe sequential synchronization, not simultaneous co-editing. Open portal pages reload the latest revision when the browser regains attention; an artifact already embedded in an AI conversation keeps what it was given until that client opens it again. Shared artifacts remain read-only; edits require the owning Stackyapper user in the owning workspace.

Authoring formats

stackyapper.ui/v1 is JSON data, not executable code. The root has exactly two keys: format and blocks. Supported block types are heading, text, status, metric, table, control, and work_queue.

The beta also accepts a React component written in JSX or TypeScript when it passes Stackyapper's source checks and uses only the curated artifact packages: React, React Query, Lucide icons, Recharts, and Stackyapper's artifact UI components. Your component runs sandboxed on Stackyapper's servers — no network, no browser, no credentials, no saved connections. It returns a description of the UI, and Stackyapper's own shell — the same versioned runtime in the standalone page and in compatible MCP Apps clients — renders that description. Arbitrary HTML, unsupported imports, and older unvalidated JSX remain inert backup source.

Example 1: status page

12345678{
  "format": "stackyapper.ui/v1",
  "blocks": [
    { "type": "heading", "text": "Morning service check", "level": 2 },
    { "type": "status", "label": "Backup", "value": "Healthy", "tone": "good" },
    { "type": "metric", "label": "Open alerts", "value": "2", "detail": "Review before noon" }
  ]
}

Example 2: bounded table

12345678910111213141516{
  "format": "stackyapper.ui/v1",
  "blocks": [
    {
      "type": "table",
      "caption": "Devices approaching replacement",
      "columns": [
        { "key": "device", "label": "Device" },
        { "key": "age", "label": "Age" }
      ],
      "rows": [
        { "device": "Laptop 014", "age": "4 years" }
      ]
    }
  ]
}

Example 3: governed read control

12345678910111213141516{
  "format": "stackyapper.ui/v1",
  "blocks": [
    {
      "type": "control",
      "kind": "refresh",
      "label": "Refresh open tickets",
      "description": "Runs a bounded read with your current access.",
      "binding": {
        "role": "psa",
        "tool_name": "cw_search_tickets",
        "arguments": { "query": "status/Open", "limit": 3 }
      }
    }
  ]
}

The matching revision bindings argument declares what the control may use:

123[
  { "role": "psa", "service": "connectwise", "tool_names": ["cw_search_tickets"] }
]

Operational work queues

Use work_queue when a saved artifact needs to keep the shape of a dispatch board, alert queue, or task list instead of flattening it into unrelated metric cards. It is the document's single full-page block: a histogram, local search and facets, filter chips, compact rows, and one optional governed query control. Search, facets, chips, histogram selection, sorting, density, and list copying all run locally over the bounded saved rows. The query control's fresh result is shown separately; it does not silently rewrite the saved snapshot.

1234567891011121314151617181920212223242526272829303132333435{
  "format": "stackyapper.ui/v1",
  "blocks": [
    {
      "type": "work_queue",
      "item_label": "tickets",
      "eyebrow": "Service operations",
      "title": "Dispatch Console",
      "status": "80 open",
      "histogram": {
        "label": "Open by age",
        "hint": "Select a bar to filter",
        "items": [
          { "label": "30d+", "value": "23", "tone": "warning",
            "match": { "key": "age_bucket", "value": "30d+" } }
        ]
      },
      "filters": [{ "key": "board", "label": "All boards" }],
      "columns": [
        { "key": "ticket", "label": "Ticket" },
        { "key": "age", "label": "Age", "kind": "age" },
        { "key": "age_bucket", "label": "Age bucket", "hidden": true }
      ],
      "rows": [
        { "ticket": "#42 Printer offline · Acme", "age": "31d", "age_bucket": "30d+" }
      ],
      "footer": ["ConnectWise via Stackyapper"],
      "control": {
        "label": "Query latest",
        "binding": { "role": "psa", "tool_name": "cw_search_tickets",
          "arguments": { "page": 1, "pageSize": 2 } }
      }
    }
  ]
}

Rules

Unknown keys or block types are rejected.
Every control's role and tool must also appear in the revision's immutable bindings argument.
Control arguments may contain bounded filters, but never tokens, credentials, connection IDs, or tenant selectors.
Controls never carry authorization. Stackyapper resolves the role against the current viewer, workspace, grants, risk policy, and saved credentials at click time; write or destructive operations still require confirmation.
Histogram and chip counts are whole numbers written as strings (for example "23").

Limits

Source: 256 KiB stored; hosted stackyapper.ui/v1 document: 64 KiB.
Hosted document: 100 blocks; each string: 4 KiB UTF-8.
Table: 12 columns and 50 rows.
Work queue: 16 declared columns, 50 rows, 6 facets, 4 chip groups, 6 histogram items, and 12 chip items per group.
Control arguments: 8 levels and 256 JSON nodes.
Backup package: 400 KiB; export is returned in bounded 4 KiB chunks.
Active artifacts: 250 per workspace; retained revision history: 50 revisions.

Backups

stackyapper.artifact/v1 is a deterministic, backup-only JSON package. It contains the title, description, source, and reviewed bindings. Its SHA-256 checksum detects corruption; it is not a signature and does not prove who created the package. Import validates the checksum and artifact format, removes all original identifiers, and creates a new private artifact owned by the importing viewer with "Imported copy" appended to its title.

Do not edit a package by hand. Export it again after changing the artifact.

Safe authoring checklist

Prefer small summaries and explicit bounded queries.
Include only data the intended viewers are allowed to see.
Declare every control tool in the revision bindings.
Use only the curated artifact packages; external packages and network imports are unavailable.
Never place secrets, customer payloads, or credential identifiers in source.
Expect controls to fail when the viewer lacks current permission.
Treat export as recoverability, not provenance or authorization.