# Long-document handoff without POST

## Status

This document defines the pasteToPrint stage 5 handoff for AI output that does
not fit the portable 8,000-character deep-link profile. It provides two local,
user-controlled routes:

1. a UTF-8 `.ptdf` file;
2. the optional **Open in pasteToPrint** browser extension.

Neither route creates a server document session or sends document content in an
HTTP `POST`. Loading the pasteToPrint application still uses a normal HTTPS
`GET`. Every import is validated, previewed and explicitly accepted or rejected
by the user.

## Route A: `.ptdf` file

An AI client with artifact or file-generation support should:

1. build a complete PTDF 1.0 document;
2. use the exact wire identifier `schemaVersion: "ptp.document/1"`;
3. validate the document against the published JSON Schema;
4. serialize it as UTF-8 JSON without Markdown fences or explanatory text;
5. name the artifact `document.ptdf` or `document.ptdf.json`;
6. use media type `application/vnd.pastetoprint.ptdf+json` when the client can
   set it;
7. give the file to the user without silently truncating or simplifying it.

The user can then:

- drag the file anywhere over the pasteToPrint editor;
- choose **Import PTDF** and select it;
- open the file with an installed pasteToPrint PWA on platforms that support
  web-app file handlers.

All three paths open the same PTDF validation dialog. Dropping or opening a
file never changes the editor automatically.

The browser-side source limit is 5 MiB. The decoded document must also satisfy
all PTDF 1.0 limits. A `.json` file can be selected manually or dropped, but
portable AI artifacts should use the unambiguous `.ptdf` or `.ptdf.json`
extension.

PWA file handling is declared in
`assets/favicon/site.webmanifest`. Availability depends on the browser,
operating system and whether the PWA is installed. The regular file picker and
drag-and-drop path remain the compatibility fallback.

## Route B: browser-extension radar

Source files are in
[`integrations/browser-extension/`](integrations/browser-extension/). The
Manifest V3 extension currently declares adapters for:

- ChatGPT at `chatgpt.com` and `chat.openai.com`;
- Gemini at `gemini.google.com`;
- Claude at `claude.ai`;
- Microsoft Copilot at `copilot.microsoft.com`.

### Install from the workspace

Chrome:

1. open `chrome://extensions`;
2. enable **Developer mode**;
3. choose **Load unpacked**;
4. select `integrations/browser-extension`.

Microsoft Edge uses the same steps at `edge://extensions`.

This source build is intended for development and controlled deployment. A
store release should be separately signed, reviewed and versioned.

### User flow

The extension adds **Open in pasteToPrint** below detected assistant responses.
Only a direct click starts a transfer.

```text
AI response DOM
  -> user clicks Open in pasteToPrint
  -> extension captures that one response
  -> pasteToPrint popup performs nonce/origin handshake
  -> response travels through window.postMessage
  -> pasteToPrint validates and shows a preview
  -> user chooses append, replace or cancel
```

If the clicked response contains a code block with a JSON object whose exact
wire identifier is `ptp.document/1`, the extension sends the object as
`pasteToPrint.document`. pasteToPrint then runs the full PTDF validator and
semantic renderer. Otherwise the extension sends the visible response as a
plain-text `pasteToPrint.import` item. It never treats arbitrary AI-generated
HTML as trusted markup.

The structured message envelope is:

```json
{
  "type": "pasteToPrint.document",
  "version": 1,
  "nonce": "per-transfer secure random value",
  "document": {
    "schemaVersion": "ptp.document/1",
    "blocks": [
      {
        "type": "paragraph",
        "text": "AI-generated document"
      }
    ]
  }
}
```

The envelope uses the existing `pasteToPrint.connect`,
`pasteToPrint.ready` and `pasteToPrint.result` handshake. The receiver checks
the exact source origin, popup window, protocol version and nonce before
accepting content.

### Permissions and privacy

The extension:

- has no background worker and requests no optional browser permissions;
- runs only on the five explicitly listed AI-chat origins;
- does not read cookies, passwords, browser history or the clipboard;
- does not call a pasteToPrint document API;
- does not capture or transfer a response until its button is clicked;
- sends the selected response only to the newly opened pasteToPrint window
  using an exact `postMessage` target origin;
- cannot confirm the import, print or export for the user.

The AI provider already has access to content written in its chat. The selected
response is also visible to installed extensions with access to that provider.
Do not place passwords, API keys, private keys, payment-card data or other
secrets in either route.

### Limits and fallback

- Plain-text extension transfers are limited to 500,000 JavaScript
  characters.
- Structured PTDF extension transfers are limited to 5 MiB before the full
  PTDF schema limits are applied.
- Pop-ups must be permitted for the AI-chat origin.
- Provider DOM changes can temporarily break an adapter. The `.ptdf` file route
  remains provider-independent.
- Content is never truncated to satisfy a limit.

For unsupported providers, ask the AI client to create a `.ptdf` file. For
short content, prefer
[`INLINE-TEXT-DEEP-LINK-V1.md`](INLINE-TEXT-DEEP-LINK-V1.md) or
[`INLINE-PTDF-DEEP-LINK-V1.md`](INLINE-PTDF-DEEP-LINK-V1.md).

## PTDF 1.0 compatibility profile

For a targeted handoff to an unknown receiver, generate the portable
`portrait` + `blank` profile. Preserve `landscape` or one of the six
`coloring_*` template IDs only when the receiver advertises the current
`2026-08-01` capabilities, or when creating a standalone current-revision file
for the user. Never add a revision member to the JSON.

Complete file-route examples are available as
[`landscape-example.json`](api/document-schema/v1/landscape-example.json) and
[`coloring-drawing-example.json`](api/document-schema/v1/coloring-drawing-example.json).
The second file contains a raster fallback only. A client flattening an editable
drawing must visibly report that layers, vectors, editable shapes, history and
drawing metadata do not survive the handoff.