0da15818ad
Picks the mark from 95c93f9 over the one I drew: at the 16–18px the dock actually renders, a solid fill reads and an outlined page does not, and pairing with pdf-editor's red badge makes the two editors obviously a set. It moves into icon.svg rather than living only as a data URL in the manifest, so make-icons.mjs keeps deriving the PNGs and addon.json's copy from one drawing. Same picture as before, one source instead of three places to forget.
93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 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.
|