QOffice/tasks/ollama-gemma-qword-header-footer.md

Ollama/Gemma Task: QOffice Next Iteration

You are Gemma running through Ollama. Work on the local repository:

G:\Repos\QOffice

Project objective: QOffice is a cross-platform Russian-language office suite intended to move toward Microsoft Office-like functionality. It contains separate applications: QWord, QExcell, QPowerPoint, and QOutlook. Microsoft Office file compatibility is a core requirement.

Current verified repository state:

• git status --short --branch returned ## main...origin/main.
• Latest commit before this task: 5487d04 Add QPowerPoint slide size support.
• QWord already has DOCX import/export, page setup controls, and a Microsoft Word-like ribbon.
• QWord does not yet implement DOCX header/footer support.

Iteration Goal

Implement QWord support for Microsoft Word / DOCX headers and footers.

The feature must be real DOCX compatibility work. Do not implement this only as internal JSON state. Import and export must read and write actual DOCX header/footer parts or clearly explain why that is impossible after inspecting the local docx package API.

Files To Inspect First

First check for local project instructions:

rg --files -g AGENTS.md

Then inspect these files before editing:

• src/types.ts
• src/data/sampleData.ts
• src/App.tsx
• src/io/wordOffice.ts
• src/io/wordOffice.test.ts
• src/io/wordOfficeImport.test.ts
• src/features/qword/QWord.tsx
• src/features/qword/QWord.test.tsx

Verified Starting Points

• src/types.ts: WordDocument currently has id, title, updatedAt, html, and optional pageSetup.
• src/io/wordOffice.ts: importDocxFile imports DOCX through mammoth, styledDocxHtmlFromArrayBuffer, and docxPageSetupFromArrayBuffer.
• src/io/wordOffice.ts: exportDocxBlob currently accepts only pageSetup in its options object.
• src/io/wordOffice.ts: lastDocxSectionProperties already finds the final w:sectPr.
• src/features/qword/QWord.tsx: openDocx applies imported title, html, and pageSetup.
• src/features/qword/QWord.tsx: saveDocx passes only pageSetup into exportDocxBlob.
• QWord's layout ribbon tab already contains page setup controls.

Implementation Requirements

1. Data model:

   Add optional QWord document fields. Preferred names:

   headerHtml?: string;
   footerHtml?: string;
   

   Existing saved documents without these fields must remain valid.

2. DOCX import:

   • Read word/document.xml.
   • Find the final applicable w:sectPr.
   • Read w:headerReference and w:footerReference.
   • Resolve their relationship ids through word/_rels/document.xml.rels.
   • Read the corresponding word/header*.xml and word/footer*.xml parts.
   • For this first iteration, support the default reference type.
   • Do not break documents that also contain first or even references; those can be ignored for now.
   • Convert header/footer content into HTML using the existing wordOffice.ts helper patterns. Preserve at least paragraphs and basic inline text styling.

3. DOCX export:

   • Extend exportDocxBlob options to accept headerHtml and footerHtml.
   • Use the local docx package API to create real DOCX header/footer parts if available.
   • Reuse the existing HTML-to-DOCX block pipeline where practical.
   • Preserve existing pageSetup behavior.
   • Generated DOCX must contain real header/footer parts and relationships.

4. QWord UI:

   • Add Russian-language controls for header and footer.
   • Preferred location: QWord layout ribbon tab near page setup.
   • Do not add a right sidebar.
   • Use clear Russian labels, for example:
     • Верхний колонтитул
     • Нижний колонтитул
   • Editing these fields must call onChange with updated document.headerHtml and document.footerHtml.
   • openDocx must apply imported header/footer fields.
   • saveDocx must pass header/footer fields to exportDocxBlob.

5. Tests:

   Add focused regression tests:

   • Import DOCX with headerReference and footerReference; assert imported headerHtml and footerHtml.
   • Export DOCX with header/footer; assert header/footer parts and relationships exist.
   • Roundtrip export -> import; assert header/footer values survive.
   • QWord UI test: changing header/footer controls calls onChange with headerHtml and footerHtml.

Verification Commands

Run the narrow test set first:

npx vitest run src\io\wordOffice.test.ts src\io\wordOfficeImport.test.ts src\features\qword\QWord.test.tsx

If the narrow tests pass, run:

npm run build
npm test
npm audit --audit-level=high

Constraints

• Do not touch unrelated files.
• Do not revert user changes.
• Do not run destructive git commands.
• Do not add dependencies unless necessary.
• Follow the existing project patterns.
• If you are only an LLM without filesystem access, return a unified diff patch and verification commands.
• If you are running inside an agent with filesystem access, edit the files directly but do not commit or push.

Final Response Required

Report:

• changed files;
• tests and command results;
• exactly how DOCX import/export was implemented;
• any remaining risks or unverified behavior.