pdf

type Annotation struct {
	// ID is the stable client-assigned identity (so a re-save updates an
	// existing annotation rather than duplicating it).
	ID string `json:"id,omitempty"`
	// Page is the 1-indexed page number the annotation lives on.
	Page int `json:"page,omitempty"`
	// Type is the annotation kind ("highlight", "stamp", "drawing", …). The
	// set is open: an unknown type round-trips without rejection.
	Type string `json:"type,omitempty"`
	// Rect is the hit box in PDF user space as [x, y, w, h] (origin
	// bottom-left). A slice rather than a fixed [4]float64 so a malformed
	// entry cannot fail the whole overlay parse — the raw DocJSON is the
	// authoritative record either way.
	Rect []float64 `json:"rect,omitempty"`
}

type ExportRequest struct {
	DocID string // persistence key
	Kind  string // "export" | "download" | "print" | "redact"
	Bytes []byte // the produced PDF bytes
	// Filename is the frame's suggested name, already sanitised of path
	// separators and Content-Disposition metacharacters. It is a HINT: the
	// handler decides where bytes actually go, and may ignore it. Empty when
	// the frame offered none.
	Filename string
	// Report is the in-frame verification report — for a redact export, the
	// evidence that the content under every rect is gone. Opaque JSON: the
	// frame owns its shape.
	//
	// It rides an HTTP header, so it is bounded. When a report would exceed
	// that bound the adapter substitutes a compact record carrying the same
	// verdicts plus "truncated":true — the detail can be lost, the VERDICT
	// never is, and a host must not read a missing report as a pass. Nil means
	// the frame sent none at all (a plain export, not a redaction).
	Report json.RawMessage
}

type Mode uint8

type MountConfig struct {
	DocID     string // persistence key (default "demo")
	MinHeight string // initial iframe height before first resize (default "480px")
	Doc       string // optional initial overlay JSON, server-rendered for reload round-trip
}

type Option func(*Plugin)

type Overlay struct {
	// SchemaVersion is the interchange version ("pdf-v1"). Echoed verbatim.
	SchemaVersion string `json:"schemaVersion,omitempty"`
	// Src binds the overlay to the external PDF it was authored against. The
	// frame recomputes src.sha256 on load and refuses to apply annotations on
	// mismatch, so an overlay never silently paints boxes at stale coordinates.
	Src Source `json:"src,omitempty"`
	// Annotations is the ordered list of markup (highlights, stamps, drawings,
	// …). Only the common fields are typed; see the note on [Annotation] for
	// where the type-specific ones live.
	Annotations []Annotation `json:"annotations,omitempty"`
	// FormFields maps an AcroForm field name to its value. Values are opaque
	// JSON (string / bool / number / …): typed as json.RawMessage rather than
	// any so the struct stays precise without modelling every field shape.
	FormFields map[string]json.RawMessage `json:"formFields,omitempty"`
	// Redactions is the ordered list of regions to remove at export. Redaction
	// is destructive and irreversible; each rect may carry a reason label.
	Redactions []Redaction `json:"redactions,omitempty"`
	// PageOps is the ordered list of page operations (rotate / delete / move /
	// insert / append) applied at export.
	PageOps []PageOp `json:"pageOps,omitempty"`
	// Rev is the optimistic-concurrency revision. A save whose rev does not
	// match the stored revision loses the race and surfaces as [ErrConflict]
	// (HTTP 409), so two editors cannot silently clobber each other.
	Rev int `json:"rev,omitempty"`
}

type PageOp struct {
	// Op is the operation: "rotate", "delete", "move", "insert", or "append".
	Op string `json:"op,omitempty"`
	// Page is the 1-indexed target page (the page being rotated/deleted/moved,
	// or the anchor for insert/append).
	Page int `json:"page,omitempty"`
	// Value is the operation parameter (e.g. rotation degrees for "rotate", or
	// the source page for "move"/"insert").
	Value int `json:"value,omitempty"`
}

type Plugin struct {
	// contains filtered or unexported fields
}

type Redaction struct {
	ID     string    `json:"id,omitempty"`
	Page   int       `json:"page,omitempty"`
	Rect   []float64 `json:"rect,omitempty"`
	Reason string    `json:"reason,omitempty"`
}

type SaveRequest struct {
	DocID         string  // persistence key (the mount marker's data-fui-plugin-docid)
	Doc           Overlay // parsed overlay (zero-valued if the body failed to parse)
	DocJSON       string  // raw canonical overlay JSON (verbatim, authoritative)
	SchemaVersion string  // interchange version ("pdf-v1")
	Rev           int     // optimistic-concurrency revision carried by the overlay
}

type Source struct {
	// Kind is how the host resolves the PDF: "url" (a fetchable location) or
	// "id" (an opaque key the host's [WithSource] understands). The host
	// adapter fetches /doc/{ref}; the frame never does.
	Kind string `json:"kind,omitempty"`
	// Ref is the url or id; it is the {id} path segment of GET /doc/{id}.
	Ref string `json:"ref,omitempty"`
	// SHA256 binds the overlay to exact bytes. On load the frame recomputes it
	// and, on mismatch, refuses to apply annotations (soft warning over plain
	// http:// to a non-localhost host — never a hard fail).
	SHA256 string `json:"sha256,omitempty"`
	// Pages is the page count of the referenced PDF, cached in the overlay so
	// the frame can lay out the page rail before the bytes arrive.
	Pages int `json:"pages,omitempty"`
}