Word Add-in

Repository layout

office-addins/word/
├── assets/
├── docs/
│   └── sources.md
├── eslint.config.mjs
├── manifest.xml
├── package.json
├── tsconfig.json
├── webpack.config.js
├── src/
│   ├── taskpane.css
│   ├── taskpane.html
│   ├── taskpane.ts
│   ├── types.ts
│   ├── styles/
│   │   ├── base.css
│   │   ├── clauses.css
│   │   ├── chat.css
│   │   ├── feedback.css
│   │   ├── pro-forma.css
│   │   ├── shell.css
│   │   └── ...
│   ├── api/
│   │   ├── auth.ts
│   │   ├── chat.ts
│   │   ├── client.ts
│   │   ├── clauses.ts
│   │   ├── index.ts
│   │   └── pro-forma.ts
│   ├── shared/
│   │   ├── dom.ts
│   │   ├── errors.ts
│   │   ├── html.ts
│   │   ├── tabs.ts
│   │   └── toast.ts
│   ├── word/
│   │   ├── draft-format.ts
│   │   ├── host.ts
│   │   └── insert.ts
│   ├── clauses/
│   │   ├── detail.ts
│   │   ├── filters.ts
│   │   ├── grouped-results.ts
│   │   ├── index.ts
│   │   ├── modal.ts
│   │   ├── state.ts
│   │   └── types.ts
│   ├── pro-forma/
│   │   ├── draft-insert.ts
│   │   ├── index.ts
│   │   ├── profile-results.ts
│   │   ├── state.ts
│   │   └── status.ts
│   ├── chat/
│   │   ├── index.ts
│   │   ├── state.ts
│   │   ├── types.ts
│   │   └── view.ts
│   └── feedback/
│       ├── index.ts
│       ├── types.ts
│       └── view.ts

Run and verify

Prepare and run each side:

cd /home/axel/projects/hugo/source/main/office-addins/word
npm install
npx office-addin-dev-certs install
npm run build
npm run validate
npm run dev

For local end-to-end checks, run Hugo in one terminal and the add-in in another, then open:

cd /home/axel/projects/hugo/source/main
npx wrangler dev --local --local-protocol https --port 8788

cd /home/axel/projects/hugo/source/main/office-addins/word
npm run dev

https://localhost:3000/taskpane.html?api=https://localhost:8788

Authentication flow

Startup in office-addins/word/src/taskpane.ts calls ensureAccess(), then ping(): GET /api/users/me.

On 401 or network failure (most often status 0 when cookie flow is missing), the taskpane opens an Office dialog to /auth/addin-complete.

/auth/addin-complete is handled by registerWordAddinAuthRoutes and posts back to Office via Office.context.ui.messageParent():

{ "type": "hugo-addin-session", "token": "<short-lived JWT>", "expiresAt": "<ISO timestamp>" }

The token is stored in session storage under hugo_word_addin_session and sent on add-in API calls with Authorization: Bearer ....

Endpoint bridge

Word Web cannot reliably send CF Access cookies in the taskpane iframe. The client routes same-origin traffic through /addin/word-api/api/... with the bearer token.

Bridge behavior comes from registerWordAddinBridgeRoutes:

• Requires authKind === 'addin_session' from the worker middleware.
• Only allowlisted paths under /api/... are forwarded to existing app handlers.
• /addin/word-feedback and /addin/word-feedback/draft use the same add-in token path but are intentionally separate from the generic API bridge.

Allowed bridge routes are exactly:

• GET: /api/users/me, /api/funds, /api/clause-categories, /api/investor-categories, /api/fund-categories, /api/gps, /api/lp-countries, /api/investors, /api/clauses/search, /api/chat/status, /api/lp-profile/facets, /api/lp-profile, /api/clauses/:id, /api/funds/:fundId/clauses, /api/funds/:fundId/clauses/search.
• POST: /api/export-template/draft, /api/chat.

Tabs

Insertion semantics

Clause insertion

Clause text insertion from search and chat uses:

• selection.insertText(..., Word.InsertLocation.replace) when no clauses-body anchor exists.
• When an existing clauses-body content control is found, it inserts paragraphs directly into that anchor.

Pro-forma insertion

• Desktop Word inserts via selection.insertFileFromBase64.
• Word Web inserts via selection.insertOoxml and requests ?format=ooxml.
• After insertion, the add-in writes comparable clauses into the inserted template’s clauses-body control.
• Heading and body style hints from heading2_style and normal_style are applied as direct formatting.

Pro-forma flow (server + add-in)

1. Resolution: the draft endpoint resolves template with fund override -> sponsor default -> built-in starter (or sponsor-only default when no fund is selected).
2. Render: it renders template data with empty clause loop, normalizing a clauses-body anchor.
3. Response: payload includes { format, body, filename, source, heading2_style, normal_style }, where format is docx or ooxml.
4. Insert: desktop inserts DOCX from base64; web inserts OOXML.
5. Post-insert: comparable clause cards are formatted and appended into the content control when available.

Chat architecture

The backend uses one clause tool plan per request. Supported modes are:

• examples → clause cards for insertion/copy.
• count → count summary.
• breakdown → grouped aggregate result.

Example response shape:

{
  assistant: string,
  clauses?: ChatClauseCard[],
  meta: { mode: 'examples' | 'count' | 'breakdown'; result_count: number; latency_ms: number }
}

Feedback

A floating widget posts via POST /addin/word-feedback and loads draft state from GET /addin/word-feedback/draft. Both routes are associated with the shared route template /addin/word/taskpane in admin feedback handling.

Endpoints used

Known limits

1. Chat is intentionally narrow and single-tool today.
2. Clause tab inserts remain plain text.
3. Word Web pro-forma insertion depends on OOXML-friendly templates.