OnlyOffice Hidden Numbering Rendering Mismatch

Do not use for:

• REF / SEQ / cross-reference fields fixed by F9 / Update Fields
  → use word-cross-reference-numbering-triage
• left side clipped / offset / unreadable viewport in OnlyOffice
  → use onlyoffice-preview-left-clipping
• uploaded PDF corruption, garbled text, Chrome Print flattening, or PDF encoding issues
  → use pdf-upload-visual-artifacts
• backend save / conversion failures where the downloaded DOCX itself is already wrong

First identifiers to collect

• {workspace_id}
• {cluster}
• {contract_id}
• {contract_version_id}
• whether the issue is in:
  • View Contract
  • embedded OnlyOffice editor
  • ONLYOFFICE Desktop Editor
  • Word Desktop
• whether platform downloaded DOCX and downloaded PDF look correct locally

Useful admin URL pattern:

https://api.{cluster}.spotdraft.com/admin/contracts_v3/contractversion/{contract_version_id}/change/?_changelist_filters=contract_id%3D{contract_id}

Relevant code paths

Contract preview path

• angular-frontend/apps/spotdraft-fe/src/app/contract-render/contract-detail-v2/contract-detail-v2.component.ts
• angular-frontend/apps/spotdraft-fe/src/app/contract-render/contract-detail-v2/contract-detail-v2.component.html
• angular-frontend/apps/spotdraft-fe/src/app/contract-render/only-office-viewer/only-office-viewer.component.ts

When the contract is in the WOPI-backed redlining path, the contract page selects WOPI_OO_VIEW and mounts app-only-office-viewer, which loads the DOCX from:

/inline_editor/{user_id}/downloads/{editable_document_id}/

That makes the first confirmed failure point the OnlyOffice render of the editable DOCX, not the upload itself.

Template / editor path

• angular-frontend/apps/spotdraft-fe/src/app/docx-template/docx-template-preview/docx-template-preview.component.ts
• angular-frontend/apps/spotdraft-fe/src/app/onlyoffice/onlyoffice-editor/onlyoffice-editor.component.ts

The generic OnlyOffice editor path exposes initialZoom; template preview uses FIT_TO_WIDTH. This is useful context for nearby OO preview issues, but for this skill the decisive signal is whether the same DOCX renders badly in OO but correctly in Word.

Backend note

If the downloaded DOCX remains correct, do not start with backend mutation theories. The incident-backed pattern is that storage and download are intact while OnlyOffice interprets list markup differently.

Investigation workflow

Step 1: Prove the bytes are still good outside OnlyOffice

Check all of these before escalating:

1. Open the customer's original DOCX in Word Desktop
2. Download the same contract from SpotDraft as DOCX
3. If available, also download PDF
4. Compare numbering outside OnlyOffice

If Word Desktop and downloaded artifacts still look correct, the problem is not “SpotDraft permanently rewrote the numbering.”

Step 2: Reproduce in another OnlyOffice surface

Open the same DOCX in:

1. SpotDraft View Contract
2. SpotDraft embedded OnlyOffice editor
3. ONLYOFFICE Desktop Editor

If OO Desktop reproduces the same numbering drift, the issue is strongly tied to OnlyOffice’s interpretation of the source OOXML, not a SpotDraft-only frontend bug.

Step 3: Inspect the source DOCX for latent numbering

In Word Desktop, reveal formatting marks / hidden paragraph structure and inspect the affected section.

Look for:

• blank numbered paragraphs
• hidden list items
• numbering carried on empty lines
• multiple nested list levels that Word suppresses visually in normal view

If those extra numbered structures become visible in Word once formatting is shown, treat the source DOCX as already containing the problematic numbering. In this pattern, OnlyOffice is surfacing it, not inventing it from nothing.

Step 4: Separate this from cross-reference / field refresh issues

Ask one key question:

• Does F9 / Update Fields fix the numbering?

If yes, this is likely field refresh / REF / SEQ behavior, not hidden list structure. Branch to word-cross-reference-numbering-triage.

If no, and OO Desktop still reproduces the bad numbering, stay in this skill.

Step 5: Decide whether the fix belongs in the document or the platform

Use this evidence table:

Mitigation / workaround

Best fix

Clean the source document in Word Desktop and upload the corrected DOCX.

Practical cleanup options:

• remove hidden / empty numbered paragraphs
• rebuild the affected list structure in Word
• re-save the document after normalizing list formatting

Fast fallback

If the customer is blocked only on preview fidelity:

• use Word Desktop or the downloaded DOCX/PDF as the source of truth for review
• avoid relying on OnlyOffice preview for the affected version until the source DOCX is cleaned

When cleanup is hard

If the exact hidden numbering is hard to isolate, try a conservative normalization pass:

• open in Word or Google Docs
• save a fresh DOCX
• re-upload and retest

Use this only as a mitigation. If the customer needs document-perfect parity, prefer explicit source cleanup over repeated blind round-trips.

Telemetry guidance

Do not spend the first 30 minutes in BigQuery, logs, or traces for this class of issue.

Why:

• this is often a client-side / renderer-side mismatch
• incidents of this type frequently have no useful backend error
• the highest-signal artifacts are the DOCX itself and how it behaves across Word vs OnlyOffice

Use logs / telemetry only if:

• downloaded files are also wrong
• the problem began right after a known release or config change
• multiple unrelated documents started failing at once
• save / publish actions appear to alter bytes unexpectedly

Escalation triggers

Escalate to the editor / platform owner when:

• the same DOCX is correct in OO Desktop but wrong only in SpotDraft
• the cleaned / normalized DOCX still reproduces in OnlyOffice
• many documents fail with the same pattern after a release
• support cannot find any latent numbering in Word but OO still inserts extra lines
• the customer needs a product-level guarantee of Word-vs-OnlyOffice parity for this document class

When escalating, attach:

• original DOCX
• downloaded DOCX from SpotDraft
• Word screenshot with formatting revealed
• OnlyOffice screenshot showing extra numbered lines
• contract / workspace identifiers

Related incidents and references

Connections to other skills

• word-cross-reference-numbering-triage
  Use when numbering fixes after F9 / Update Fields
• onlyoffice-preview-left-clipping
  Use when the issue is viewport / clipping rather than list structure
• pdf-upload-visual-artifacts
  Use for uploaded PDF corruption or encoding problems, not DOCX list markup surfaced by OO

Incident-backed example pattern

Example only, not a reusable constant:

• customer reports numbering changed from hierarchical clauses like 3 -> 3.1 -> a) into extra visible numbered lines such as 3., 1., 2., 3.
• upload and download looked fine
• SpotDraft OnlyOffice preview and OO Desktop both reproduced
• Word Desktop revealed hidden numbering / formatting in the source DOCX

When you see that combination, prefer document cleanup over backend debugging.