# Word editor — a Theseus extension

Opens, edits and saves Word documents (`.docx`) in a full Theseus tab, and
exports them as PDF.

Saving comes in three shapes. **Save** drops a copy in your downloads until the
document has a home; **Save as…** opens a real file dialog where the extension
you type — `.docx` or `.pdf` — decides the format, and from then on Save writes
straight to that file; **PDF** is the one-click export. PDFs are rendered by
Chromium's own print pipeline from `lib/doc-css.js`, the same stylesheet the
editor displays, on the paper size the document itself specifies — so the
export matches the preview rather than being a second opinion about it.

It is a first-party extension: written here, signed with the Silent Mode
operator key, and updated over the channel at
`theseus.x/extensions/docx-editor/` like every other add-on Theseus ships.
It does not go through the community catalogue, which is for extensions
published by whoever owns a BNS name.

It ships inside Theseus, so a fresh install already has it and Settings
lists it under **Built into Theseus**; the channel above then updates it
between releases without waiting for one. That is the same arrangement as
screenshot, aegis and pdf-editor, and it is what gives a user their first
copy at all — Settings can only *install* from the community catalogue, so
an extension that is neither bundled nor catalogued has a working update
channel and no way in.

The cost is about 400 KB compressed in the installer, most of it the
vendored editor libraries.

## The icon

`icon.svg` is the one drawing. `npm run icons` rasterises it to
`icon-16/32/48/128/256.png` and writes a minified copy into `addon.json`'s
`icon` field, which is what the dock button and the catalogue card read — so
there is never a second version to keep in step.

It is a blue document badge, paired with pdf-editor's red one so the two
editors read as a set in the dock — a solid fill stays legible at the 16–18px
the dock actually renders, which an outlined page does not.

Deliberately not Microsoft's Word icon: their mark is a blue sheet carrying a
white W, and dressing our extension up as theirs would be both a legal
problem and a dishonest one. A folded-corner page is the universal document
glyph, and "DOC" is the file format rather than anyone's trademark.

## Building

The vendored libraries (mammoth, ProseMirror, docx, JSZip) are bundled by a
build step that lives outside this folder, because mammoth needs local patches
before it can carry everything the editor edits:

    cd ../../addon-build/docx-editor
    npm install
    npm run build        # writes vendor/docx-vendor.js here
    npm run icons        # re-rasterises icon.svg after editing it

`vendor/docx-vendor.js` is committed, so the extension is installable straight
from a checkout; re-run `npm run build` after touching anything under
`addon-build/`.

## Publishing

The full recipe is in [docs/ADDON-UPDATES.md](../../docs/ADDON-UPDATES.md);
the short version, signed with the operator key and always from a clean copy
of the commit rather than the working tree:

    git archive HEAD TheseusNavigator/extensions/docx-editor | tar -x -C <clean>
    node scripts/sign-addon-update.mjs         <clean>/TheseusNavigator/extensions/docx-editor         https://navigate.st/bns/theseus.x/extensions/docx-editor         "$USERPROFILE/.silentmode/ops/addon-update-key.pem" --out out/

    node ../Argus/src/lib/sia-upload.js out/docx-editor-<version>.tar.gz bns/theseus/extensions/docx-editor
    node ../Argus/src/lib/sia-upload.js out/updates.json                 bns/theseus/extensions/docx-editor

The channel lives on Sia only — nothing goes to the VPS filesystem — and is
served through the gateway at `https://navigate.st/bns/theseus.x/extensions/`.
A first release has no `updates.json` to prepend to, so it ships one holding
just its own entry. Versions must increase.

## Testing

Three levels, all re-runnable, all from `../../addon-build/docx-editor`:

    node test/roundtrip.mjs                  # the built-in fixture
    node test/corpus.mjs <folder of .docx>   # real documents
    node ../../../scratchpad/verify-docx-editor/drive.mjs   # a real Theseus, over CDP

The last one installs this folder into a throwaway profile the way the
community channel would, and is the only one that catches browser-only
breakage.

What survives a round trip, and what doesn't, is written up in
[ROUND-TRIP.md](ROUND-TRIP.md). Read that before promising anyone a Word
feature.