Mark page artifacts over Connect

Mark page artifacts over Connect

At a glance

This recipe wraps pagination chrome, including running headers and footers, page numbers, watermarks, and backgrounds, in artifact marked content over Connect transports. The chrome still appears on the page, but it stays out of the structure tree and the assistive technology reading order. The artifact tool is Enterprise-tier: NextPDF discovers it with a class_exists() probe and registers it only when nextpdf/premium is installed alongside the server. The subtype uses a typed enum (Pagination, Layout, Page, Background).

To verify the output, use the Enterprise standards-check tool, which reports against PDF/UA-2. A passing result is the tool’s own check, not an independent conformance certification.

Install

composer require nextpdf/server

Confirm that the Enterprise artifact tool is present with a tools/list call. See /connect/tool-catalog/.

Conceptual overview

Content that is not part of the logical structure is marked as an artifact and excluded from the reading order (PDF/UA-2 §8.3). Artifacts include pagination, layout, page, or background content, and are distinct from real content (PDF/UA-2 §8.3). Real content is reflected in the structure tree; artifacts are not (PDF/UA-2 §8.2.4).

The tool opens an artifact marked-content sequence of the requested subtype. Any draw operations you issue before the matching close are wrapped inside it.

API surface

Verify tool names against the running registry with tools/list. The catalog of record is /connect/tool-catalog/. This recipe does not repeat the tool count.

Code sample — Quick start

Open a Background artifact, draw the watermark, close it:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

Code sample — Production

Pair every open with a close, and verify that the page carries no orphan content:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

After you draw the footer text, close it with the end-artifact tool and run the standards check against PDF/UA-2. The structure tree must contain only the body content; the watermark and footer must be excluded.

Edge cases & gotchas

• Unknown subtype (for example "Header") is rejected. Pass one of Pagination, Layout, Page, Background.
• Close without an open fails with a depth-zero message. Always pair open and close.
• Drawing before any artifact or structure context produces orphan content and a structure-rule failure. Open a structure or artifact context first.
• Tool absent. Without nextpdf/premium, the Enterprise artifact tool is not registered, and the call fails with an unknown-tool error.

Performance

The frontmatter budget is a documentation cap. Artifact wrapping adds no measurable separate phase.

Security notes

Not applicable beyond the general Connect transport guidance.

Conformance

PDF/UA-2 mapping

Subtype	Use case
Pagination	Running headers/footers, page numbers, navigation chrome
Layout	Rules, separators, decorative borders
Page	Page-bound aids (cut marks, registration)
Background	Watermarks, background fills, branding

Tag → ISO 32000-2 §14.9 cross-ref

Claim	Clause	reference_id
Non-structural content marked as artifact, excluded from reading order	PDF/UA-2 §8.3
Artifact subtypes: pagination/layout/page/background	PDF/UA-2 §8.3
Real content in the structure tree; artifacts not	PDF/UA-2 §8.2.4

WCAG 2.2 mapping

Excluding decorative chrome from the reading order supports Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) at the content level.

A passing standards-check result is a check, not a conformance certification. An independent checker makes that determination.

Commercial context

The artifact tool is Enterprise-tier and registers only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

You invoke these tools the same way over MCP tools/call, the REST tool endpoint, and the gRPC service. All three use the shared tool executor.

HITL risk tier

Artifact emission and content drawing are caution-level; the standards check is read-only. None is approval_required by default. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

These tools do not trigger the gate unless an operator override raises one to approval_required. The envelope and single-use token contract are in /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/aria-tagged-pdf/ — landmark role mapping.
• /cookbook/connect/figure-caption/ — accessible image grouping.
• /connect/tool-catalog/ — per-tier tool set computation.
• /connect/hitl-risk-tiers/ — the risk model and the gate.