CJK vertical writing over Connect

CJK vertical writing over Connect

At a glance

This recipe embeds a Chinese, Japanese, and Korean (CJK) CIDFont with vertical-writing metrics over the Connect transports. The engine emits the PDF 2.0 vertical-metrics entries (/W2 per-glyph and /DW2 default) on the CIDFont dictionary and renders a top-to-bottom glyph stack. CJK font embedding is Enterprise-tier. The CJK font tools are discovered through class_exists() probes and register only when nextpdf/premium is installed alongside the server. The engine emits vertical metrics only when the active CID encoding is the vertical Identity encoding. Horizontal runs are unaffected.

Install

composer require nextpdf/server

Confirm that the Enterprise CJK font tools are present with a tools/list call. See /connect/tool-catalog/.

Conceptual overview

A CIDFont in vertical writing mode uses /W2 (per-glyph) and /DW2 (default) vertical metrics (ISO 32000-2 §9.7). The CMap selects horizontal or vertical writing mode (ISO 32000-2 §9.7). Vertical writing mode moves the glyph advance to the vertical axis (ISO 32000-2 §9.7). When you register the font, the pipeline parses the font’s vertical-metrics tables. It emits the dictionary entries only after you select the vertical CID encoding.

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 a tool count.

Code sample — Quick start

Create the document, register the CJK font, and select the vertical encoding:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_cjk_font",
    "arguments": {
      "document_id": "<id>",
      "family": "NotoSansCJKjp",
      "source": "/usr/share/fonts/opentype/noto/NotoSansCJKjp-Regular.otf",
      "subset": true
    }
  }
}

Code sample — Production

Select the vertical encoding, set the font, write a vertical run, and then output and inspect the CIDFont dictionary:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "set_cid_encoding",
    "arguments": { "document_id": "<id>", "font_key": "NotoSansCJKjp", "encoding": "/Identity-V" }
  }
}

The output’s CIDFont dictionary carries /W2 and /DW2. The same source omits both when rendered with the horizontal encoding. The encoding gate is the only difference, which keeps the structural reproducibility profile accurate here.

Edge cases & gotchas

• Font lacks vertical-metrics tables. The font tool warns. Pick a CJK font that includes them; a Latin-only font has none.
• Vertical encoding selected on a font without vertical metrics is an error. Fall back to the horizontal encoding or pick another font.
• Vertical text requested while the horizontal encoding is active is an error. Select the vertical encoding before the first vertical text emission.
• Encoding flipped after first text emission is rejected with a frozen-encoding error. Set the encoding immediately after you register the font.
• Tool absent. Without nextpdf/premium, the Enterprise CJK font tools are not registered, and the call fails with an unknown-tool error.

Performance

The front-matter budget is a documentation cap. Subsetting limits the per-glyph metrics array size. Disable subsetting only when a vertical run needs glyphs that the subset would drop.

Security notes

No additional notes beyond the general Connect transport guidance.

Conformance

Claim	Clause	reference_id
Vertical CIDFont uses /W2 and /DW2 metrics	ISO 32000-2 §9.7
The CMap selects horizontal vs vertical writing mode	ISO 32000-2 §9.7
Vertical writing mode advances glyphs on the vertical axis	ISO 32000-2 §9.7

Emitting the vertical-metrics entries implements the cited clauses. It is not a blanket conformance claim. A validator determines whether the overall document conforms.

Commercial context

CJK font embedding is Enterprise-tier. The CJK font tools register only when nextpdf/premium is installed alongside the server.

Connect specifics

Transport availability (MCP / REST / gRPC)

Invoke this the same way over MCP tools/call, the REST tool endpoint, and the gRPC service. All three route through the shared tool executor.

HITL risk tier

Font registration, encoding selection, and text emission are caution-level. Output requires approval when it writes a file; base64 mode does not. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

When the file-writing output path is gated, the gate returns a challenge envelope and a single-use token bound to the tool name, a nonce, and a 300-second TTL. Re-invoke with arguments._confirmation_token. See /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/font-typography/ — horizontal text and font selection basics.
• /cookbook/connect/conformance-mode/ — vertical CJK runs still require tagging for PDF/UA-2.
• /connect/tool-catalog/ — per-tier tool set computation.
• /connect/hitl-risk-tiers/ — the risk model and the gate.