fix: normalize positioned text box offsets

[jan-kubica]

Summary

• materialize zero offsets for omitted axes on positioned legacy text boxes
• preserve the normalized position through DrawingML conversion and save/reopen
• cover horizontal-only, vertical-only, and fully omitted offsets with one invariant test

Validation

• bun test packages/core/src/docx/textBoxDrawingOwnership.test.ts
• bun --filter @stll/folio-core typecheck
• bun run lint
• bun run test
• bun run typecheck
• bun run build
• bun run validate-dist

Summary by CodeRabbit

• Bug Fixes

  • Normalised missing horizontal and vertical offsets for positioned legacy text boxes.
  • Ensured text box positioning remains consistent when documents are converted, repacked, and reopened.

• Tests

  • Added coverage for preserving omitted position offsets throughout the document processing cycle.

• Chores

  • Recorded a patch release for the core package.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7330789f-7900-4da4-b113-82508990f9b8

📥 Commits

Reviewing files that changed from the base of the PR and between 460a819 and 58d0e3c.

📒 Files selected for processing (3)

• .changeset/clean-boxes-rest.md
• packages/core/src/docx/paragraphTextBoxEnrichment.ts
• packages/core/src/docx/textBoxDrawingOwnership.test.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: Lint, typecheck, test, build
• GitHub Check: Interaction e2e (playground)
• GitHub Check: Packaged-consumer build (tarballs)

🧰 Additional context used

📓 Path-based instructions (6)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Treat legal data, personal data, repository secrets, and private business or security context as sensitive; do not publish them in repository artifacts.
Preserve security, auditability, least privilege, data minimization, workspace isolation, ownership boundaries, audit trails, encryption-aware handling, and explicit access checks.
Rebase feature branches onto main, enable git rerere with autoupdate, use Conventional Commits, and make separate commits for unrelated pre-existing fixes.

Files:

• packages/core/src/docx/paragraphTextBoxEnrichment.ts
• packages/core/src/docx/textBoxDrawingOwnership.test.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx}: Prefer explicit values and thread backend discriminators through the full stack instead of hardcoding frontend defaults.
Use branded types, discriminated unions, exhaustive checks, and named domain discriminators instead of runtime discipline, boolean state flags, or invalid optional-field combinations.
Fail fast: validate at boundaries, return or throw early, minimize brace nesting, and invert conditions when possible.
Use named constants rather than string literals for domain values.
Do not assign directly to document.cookie.
Avoid spread in loop accumulators; use .push().
Prefer as const objects or union types; do not use TypeScript enums.
When a cast is unavoidable, ask before adding it and include a // SAFETY: comment explaining why it is sound; otherwise narrow with type guards, in checks, or records.
Trace type mismatches to the producing handler or query instead of casting at the consumer.
Do not annotate values the compiler already infers or pass explicit type arguments to inference-driven hooks and API calls.
Use as const satisfies T to validate large object literals without widening them.
Use .at(0) when an element may be absent; use [0] only after existence is established or with a // SAFETY: comment.
Prefer arrow functions, parameter destructuring when the intermediate variable is not reused, discriminated-union narrowing, and library utility types.
Use options/args/params objects for three or more function arguments, or for interchangeable positional arguments; reserve Props for React component props.
Keep helper-local types immediately above the helper; hoist noisy return types into nearby aliases.
Avoid expensive type instantiation in hot generic paths; prefer narrowing and keep unused large types out of inferred return positions.
Shared modules must not have module-level side effects; split reusable utilities from side-effecting singletons.
Never import test-only types into production code; use structural constra...

Files:

• packages/core/src/docx/paragraphTextBoxEnrichment.ts
• packages/core/src/docx/textBoxDrawingOwnership.test.ts

packages/core/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

packages/core/**/*.{ts,tsx}: Keep @stll/folio-core framework-neutral and React-free: never import React, React DOM, or React-package types; use minimal structural types and framework-neutral managers.
Express fidelity fixes as reusable OOXML or layout invariants, not fixture identity, source metadata, document text, or corpus-specific signals.
Keep parsing, normalization, measurement, pagination, and painting responsibilities separate; keep central pipeline files orchestration-focused.
Keep normalization and layout inputs immutable and idempotent; derive effective values instead of overwriting authored model values.
Consolidate shared OOXML syntax, units, geometry, and compatibility handling rather than allowing feature parsers to diverge.

Files:

• packages/core/src/docx/paragraphTextBoxEnrichment.ts
• packages/core/src/docx/textBoxDrawingOwnership.test.ts

**/*.{ts,tsx,md}

📄 CodeRabbit inference engine (AGENTS.md)

Do not remove or alter eigenpal/docx-editor attribution comments.

Files:

• packages/core/src/docx/paragraphTextBoxEnrichment.ts
• packages/core/src/docx/textBoxDrawingOwnership.test.ts

**/*.{test.ts, test.tsx, spec.ts, spec.tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Test only behavior that type systems, frameworks, and linters cannot guarantee; prefer invariants over examples for large input spaces.

Files:

• packages/core/src/docx/textBoxDrawingOwnership.test.ts

**/*.{test.ts,test.tsx,spec.ts,spec.tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Add a minimal synthetic regression test for each fidelity invariant and keep source documents, corpus identities, and identifying details out of tests and artifacts.

Files:

• packages/core/src/docx/textBoxDrawingOwnership.test.ts

🔇 Additional comments (3)

packages/core/src/docx/paragraphTextBoxEnrichment.ts (1)

488-492: LGTM!

.changeset/clean-boxes-rest.md (1)

1-5: LGTM!

packages/core/src/docx/textBoxDrawingOwnership.test.ts (1)

4-4: LGTM!

Also applies to: 101-120, 189-233

---

📝 Walkthrough

Walkthrough

Positioned VML text boxes now normalise missing horizontal and vertical offsets to zero. Tests verify the parsed positions across varied styles and after DOCX repacking, with a patch changeset added for @stll/folio-core.

Changes

Positioned text box offset normalisation

Layer / File(s)	Summary
Offset normalisation packages/core/src/docx/paragraphTextBoxEnrichment.ts, .changeset/clean-boxes-rest.md	Positioned VML text box shapes always include horizontal and vertical offsets, defaulting omitted values to zero; a patch changeset records the update.
Offset regression coverage packages/core/src/docx/textBoxDrawingOwnership.test.ts	Adds typed position extraction and verifies omitted-axis defaults before and after DOCX repacking and reopening.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: normalising offsets for positioned legacy text boxes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/normalize-vml-text-box-position

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}