|
|
2 недель назад | |
|---|---|---|
| .. | ||
| common | 2 недель назад | |
| docs | 3 недель назад | |
| home | 1 месяц назад | |
| img | 1 месяц назад | |
| sheets | 2 недель назад | |
| slides | 2 недель назад | |
| templates | 1 месяц назад | |
| README.md | 2 недель назад | |
| init.agi | 1 месяц назад | |
A self-hosted office suite for the ArozOS web desktop: Docs (word processor), Sheets (spreadsheet) and Slides (presentations). Three webapps, one shared framework, one Go conversion library.
This README is the developer handoff document: it explains how everything fits together, why the non-obvious decisions were made, and where to start when you continue development.
| App | Folder | Own format | Other formats |
|---|---|---|---|
| Docs | docs/ |
.docx |
.doc / .dot (import), .pdf (import and export), .odt, .html, .md, .txt |
| Sheets | sheets/ |
.xlsx |
.xls / .xlt (import), .ods, .pdf (export), .csv, .tsv |
| Slides | slides/ |
.pptx |
.ppt / .pot / .pps (import), .odp, .pdf (export), .png |
Each app saves straight into the Office format of its kind, with the editor's own copy of the document embedded in the package, so what Word, Excel and PowerPoint see is a normal file and what the suite reopens is exactly what it saved (see Documents).
All three apps are registered by the single init.agi in this
folder (module registration only — it runs with system scope, don't put
user/file logic in it).
Two more folders sit alongside them:
home/ — the suite's home page: create a document, pick up a
recent one, or start from a template. It is published to the root of the
standalone web edition (see below) and also works in place at
Office/home/index.html. Vanilla JS, no framework, no icon font.templates/ — the getting-started templates. They are
plain envelope JSON files (*.json), loaded straight into the editor as a
new unsaved document with no conversion, generated from readable literals
by node templates/build_templates.js — edit that file, not the
.json output, and keep manifest.json in step (the builder fails if
the two disagree).Browser (webapp JS) ArozOS server (Go)
┌─────────────────────────┐ agirun ┌──────────────────────────────┐
│ docs/docs.js │ ──────────► │ <app>/backend/*.agi │
│ sheets/sheets.js + _io │ JSON body │ (Otto JS VM, user scope) │
│ slides/slides.js │ │ │ requirelib("office") │
│ + common/office.js │ │ ▼ │
│ + common/*.js widgets │ │ mod/agi/agi.office.go │
└─────────────────────────┘ │ (permission + vpath glue) │
│ ▼ │
│ mod/office/... (packages) │
│ (pure converters, no I/O) │
└──────────────────────────────┘
Three layers, strictly separated:
.agi scripts in each app's backend/ folder
plus the shared common/backend/. They only
validate parameters and call the office AGI library. Keep them thin:
the Otto VM is slow and single-purpose.src/mod/office/ does every
format conversion as a pure []byte/struct transformation (no file
I/O, no globals). src/mod/agi/agi.office.go
wraps it with per-user permission checks and virtual-path handling.
API docs: the office section of
src/mod/agi/README.md — keep it and
src/web/Terminal/docs/api.json
in sync whenever you change an office.* function.mod/office is one Go package per format, all under the
imuslab.com/arozos module (the package comment in
doc.go is the authoritative map):
| Package | Role |
|---|---|
office (root) |
the envelope: native.go (open/save .docx / .xlsx / .pptx with the embedded copy), packed.go (session snapshots), formats.go (which extension opens in which app, legacy sniffing and conversion) |
model |
the three editor body schemas and their JSON helpers - every reader produces these, every writer consumes them |
docx, xlsx, pptx |
OOXML import and export, one package per app |
odf |
OpenDocument import and export (.odt, .ods, .odp) |
doc, xls, ppt |
Office 97-2003 binary formats, import only: each converts the legacy file into OOXML and hands it to docx / xlsx / pptx |
pdf |
server-side PDF export (Docs body, Sheets print model) |
metafile |
WMF / EMF (and DIB / TIFF) pictures to PNG |
internal/... |
shared plumbing: cfb (OLE2 compound files), officeart (the Escher drawing records Word, Excel and PowerPoint share), opc (writing OOXML packages), codepage, xmltree, media, htmlutil, units, fonts, slidetext, officetest |
The same front end also ships as a standalone web edition ("ArozOS Office Web"): the suite served by a plain static file server with no ArozOS behind it, so a document can be shared with someone who has no account. Documents are opened from and saved back to the visitor's own device, by the same Go code compiled to WebAssembly.
That is not a fork. Everything reaching outside the browser tab goes through
common/platform.js (OfficePlatform), which carries
both host implementations and picks one from the flags in
common/mode.js. The generator
apps/arozos_office/generate.go
copies the tree, drops the .agi backends, and flips those flags — that is
the whole build.
The documents work there the same way: mod/office is pure
[]byte/struct code with no I/O, so it compiles to WebAssembly
(src/wasm/office) and the standalone build runs the
identical code in the page — a .docx it writes is what ArozOS would have
written. generate.go always builds and ships that module, and
common/wasm.js fetches it the first time a document is opened or saved.
Two capability questions, and they are not the same:
OfficePlatform.hasBackend() — is there a server? (storage, AGI scripts,
the Sheets PDF renderer — Docs and Slides render their own PDF in the
browser and need no backend for it)OfficePlatform.canConvert() — does this build carry the Office format
code (true in ArozOS and in the standalone build)?Gate anything new on the right one (details in CONTRACT.md), or it will
be a dead menu entry out there.
Read common/CONTRACT.md before touching any
front-end code — it defines the shared OfficeApp framework (toolbar,
menus, file open/save, busy/toast/status, print), the widget libraries
(textedit.js floating format bar, colorpicker.js, charts.js,
clipboard.js, hotkeys.js), the page skeleton, and the house rules
(no emoji in source, no cross-webapp imports, ES5-ish style, must work
both in a FloatWindow and a plain tab).
The three apps share one chrome, built in common/ribbon.js
and common/office.js (API in CONTRACT.md): a title
bar with the AutoSave switch, the File and Edit menus and the ribbon's
tabs, and under it a ribbon of two-row groups, big buttons and galleries -
Microsoft Office's layout with Google Docs' File / Edit menus and flat look.
Save, Undo and Redo live in those two menus (and on their shortcuts), not
on the ribbon. Every Home tab starts with Office's Clipboard group
(OfficeRibbon.clipboardGroup): a big Paste whose label opens the paste
options, Cut, Copy (its caret lists other ways to copy) and Format Painter
as icons one under the other, and a dialog launcher opening the Clipboard
pane - everything copied or cut in any Office window of the browser tab
this session (OfficeClipboard.history, kept in sessionStorage), click an
item to paste it. Cut / Copy / Paste and Format painter are also in Edit.
The window title names the file from the moment it
starts opening (showOpening in office.js). The tabs are Word's, Excel's and PowerPoint's:
| App | Tabs |
|---|---|
| Docs | Home, Insert, Draw, Layout, References, Review, View |
| Sheets | Home, Insert, Formulas, Data, Review, View |
| Slides | Home, Insert, Draw, Design, Transitions, Animations, Slide Show, View, + Shape Format / Picture Format while such an object is selected |
There is no Design tab in Docs (the document has no theme model to put in one) and no Page Layout tab in Sheets (no print setup to put in one); add them when those exist rather than as empty tabs.
Widths. The ribbon fits itself on every resize: galleries give up tiles,
then whole groups fold into a dropdown button that opens their real controls
in a popup (lowest priority first), and the title bar closes its tabs up and
then turns them into one tab picker. At phone width (body.of-narrow,
600px and under) the ribbon is one sideways-scrolling line of icons under
the picker; Docs fits the page to the screen (a transient zoom, not saved),
Slides puts the slide strip under the slide and folds the notes away, and
Sheets narrows its name box. All of it is CSS on the same DOM - there is no
second mobile UI to keep in step.
Commands added with the ribbon (each is ordinary document content, so every format keeps it):
w:shd / w:pBdr), sort paragraphs, formatting marks (an
absolutely positioned pilcrow, so it cannot move a line), format painter,
footnotes (Ctrl+Alt+F), a table of contents (see
Docs: table of contents), margin / orientation
/ size presets, word count, page-width zoom.s.ff, s.st, s.va - written to and read from .xlsx and
.ods), merge and center, the number-format box and comma style, cell
styles and Format as Table (presets of ordinary formatting, plus a filter
on the range), AutoSum, the function library by category (spec.cat),
Show formulas (Ctrl+`), Calculate now (F9), gridlines and formula bar on
or off, freeze presets, note navigation, selection statistics.a:rPr baseline),
vertical text alignment, line spacing, find and replace across the deck
(Ctrl+H), format painter, theme / transition / animation galleries.common/sketch.js), inserted as a trimmed PNG.Slide overview (View > Slide overview, the status bar's grid button, or
Ctrl+Alt+1): the deck as a grid, like Google Slides' grid view or
PowerPoint's Slide Sorter (renderOverview in slides.js). Click selects,
double-click or Enter opens the slide, drag reorders, right-click has the
slide menu (the rail's own: new, duplicate, delete, Skip / Unskip slide,
move, background), Delete / Ctrl+D / Ctrl+M act on the slide in hand, arrows move
by card and by row, Escape goes back. The previews are the same
renderSlideContent() the rail uses, and renderThumb / renderRail keep
the grid in step with every edit; the floating control at the bottom sets
the card size (overviewSize, saved).
Skipped slides (Google Slides' Skip slide, PowerPoint's Hide Slide):
the slide menu and the Slide Show tab toggle slide.hidden
(toggleSlideSkip in slides.js). The rail and the overview fade the
preview, strike the number through and add an eye-slash; the status bar
says "(skipped)". The slide show walks past it (shownFrom in
present.js): next / previous / Home / End, starting from a skipped slide
starts at the next shown one, and the presenter view's next slide is the
next shown one. A click link to a skipped slide still opens it (backup
slides), and the Transitions / Animations Preview plays it
(showSkipped). Skipped slides stay in the deck and in every export (PDF,
PNG, print). Files carry it as pptx <p:sld show="0">, odp
presentation:visibility="hidden" and, read only, the fHidden bit of a
.ppt slide.
Go structs are the source of truth — they mirror the JS exactly:
document): model/document.go —
{html, page{size, orientation, margins(mm), columns, colGap, headerDist,
footerDist}, header, footer, headerHtml, footerHtml, footnotes[{id, html}],
lineSpacing, hfMode, pageNumbers, comments, trackChanges}. html is a
sanitized contenteditable subset (see sanitizeHtml in docs.js) — the
rich model below. header/footer are the plain-text pair the editor
types into; headerHtml/footerHtml win when set (an imported header with
its own typography, a picture, a PAGE field). lineSpacing is the
document's default multiple (1.15 when absent). hfMode (all |
except-first | none, Format > Header & footer) says which pages repeat
the header/footer; empty means all, so documents written before the
setting existed keep their behaviour.The rich model is plain HTML with inline CSS in points plus a few data attributes, so one representation is shared by the editor, the layout engine, the PDF exporter and the DOCX reader/writer:
padding-top = spacing before (a heading's is margin-top,
which collapses like Google Docs does), margin-bottom = after,
margin-left/right + text-indent = indents, border-* + padding-*
= paragraph rules and their space; data-ls (multiple),
data-lsexact / data-lsmin (pt), data-keep-next,
data-keep-lines, data-widow="0", data-page-break-before,
data-tabs="right:451.3:dot;…".ol/ul.doc-list[data-num][data-fmt][data-lvltext] with
padding-left and --doc-hang; the marker text is computed into
li[data-marker] by the layout engine (Word numbering continues across
lists that share a data-num).span.doc-tab (a real tab), sup.doc-fnref[data-fn],
span.doc-field[data-field=PAGE|NUMPAGES].width/height in pt, object-view-box: inset(…) for a crop,
img.doc-anchor for one anchored above/below the text.table.of-table with a pt width, table-layout: fixed and a
pt <colgroup>; cells state borders/padding/background inline.
data-docx="1" marks a table laid out the Word way (no spacing around
it) — one made in the editor has none and keeps docs.css's 8pt.spreadsheet): model/workbook.go —
{sheets[{name, cells{"A1":{v,s,n}}, colW, rowH, merges, freeze,
hiddenRows, charts, filter, cf}], active, names[{name, formula, sheet?}]}. names are the workbook defined names (sheet = the index of the sheet a
sheet-local name belongs to). hiddenRows is the sorted list
of 0-based rows the user hid (row-number context menu, Ctrl+Alt+9 /
Ctrl+Shift+9, click the marker to show); it round-trips as
<row hidden="1"> in xlsx. Rows a filter hides are computed, not stored. Cell v is the raw input (=-prefix =
formula, evaluated client-side in sheets/formula.js).
cf is the sheet's conditional-format rules (below) — client-side only,
so the Go structs do not model it.presentation): model/presentation.go —
{size:[960,540], theme, slides[{id, bg, bgImage, bgGrad, notes,
transition, hidden, objects[{type, x, y, w, h, rot, z, props}]}]}.
hidden: true is a skipped slide (absent otherwise). Object types: text,
image, shape, line, table, chart, video, audio. size is
960 wide and as tall as the deck's shape - a 4:3 PowerPoint deck is
960x720, never squeezed into 16:9 (the editor, present mode and the PDF
exporter all take it from the deck; setSlideSize() in slides.js).Handled by native.go +
common/backend/document.agi
(office.saveDocument / office.loadDocument), and by the same Go code as
WebAssembly in the web edition (documentFile / spreadsheetFile /
presentationFile in src/wasm/office):
arozos/document.json (media
as asset://<name> refs), arozos/manifest.json (a fingerprint of every
OOXML part, and which assets are the same bytes as an OOXML part, so a
picture is stored once) and arozos/assets/ for media the OOXML does not
hold (video, audio, a chart's source). A root relationship of our own type
ties it in and every part has a content type, so the package stays valid
OPC; office applications ignore relationship types they do not know.media?file= link; office.saveDocument reads it server side
(for the OOXML part and the embedded copy both, one read). office.
loadDocument writes a document's media into a working folder and links
it - for an imported file too, so a 20 MB .docx of photos opens as a small
JSON body.tmp:/ and belong to one editor window.
An opened document's pictures go to tmp:/.appdata/Office/cache/<window>/,
pictures dropped in before a save to tmp:/.appdata/Office/uploads/<window>/
and oversized request payloads to tmp:/.appdata/Office/tmp/ (<window> is
a random id the page makes, INSTANCE in common/platform.js). The window
deletes its folders when it closes (office.releaseWorkdir, sent as a beacon
on pagehide and from the float-window close guard), and every two hours
while it stays open refreshes them (office.touchWorkdir) so the nightly tmp
sweep, which removes whatever has not changed for a day, leaves them alone.
A window closed with unsaved changes keeps them: the draft in the browser
still links them, and the sweep takes them a day later. Should a picture's
working copy be gone anyway, office.saveDocument refuses the save instead of
writing the file without it. A picture pasted from another window links into
that window's folder, so the receiving window copies it into its own
(OfficePlatform.adoptSrc). Earlier versions kept these folders under
user:/.appdata/Office/, where nothing removed them; prepare sweeps them by
age.agirunLarge gzips a body over 64 KB and
uploads it; office.readPayload gunzips it (see CONTRACT.md).packed.go, office.packToFile /
office.unpackToWorkdir), written to user:/.appdata/Office/session/.What each OOXML file shows to other programs, beyond what the embedded copy keeps for the suite:
| Word / Excel / PowerPoint see | kept only in the embedded copy | |
|---|---|---|
| Docs | text, styles, lists, tables, pictures, footnotes, headers/footers, comments (resolved state included) and suggestions as tracked changes (docx/review.go), "Suggest edits" as trackRevisions |
- |
| Sheets | cells, formulas, styles (font, size, colours, bold / italic / underline / strikethrough, horizontal and vertical alignment, wrap), merges, freeze panes, hidden rows, charts, notes, defined names, conditional formats (every editor condition, xlsx/cf.go), tab colours, the filter range |
pivot settings, the filter's hidden values |
| Slides | every object, transitions (fade / push / zoom), skipped slides (show="0"), click links (to a slide or a URL), line dashes and ends (a square end as a diamond, an open end as the filled one - PowerPoint has neither), picture frames, callout tips, charts as pictures, videos as their poster frame |
groups, entrance animations, live charts, the video/audio files, the exact line end |
The reverse holds too: comments, tracked changes, conditional formats, tab colours, filter ranges, transitions, hidden slides and click links made in Office applications are read back.
Each app also opens the legacy binary format of its kind: Docs .doc /
.dot, Sheets .xls / .xlt, Slides .ppt / .pot / .pps. They are
never written - the suite has no legacy export.
mod/office/doc, xls and ppt each read the OLE2
compound file (internal/cfb) and write the equivalent OOXML package
(doc.ToDocx, xls.ToXlsx, ppt.ToPptx), following the structure of
LibreOffice's importers (sw/source/filter/ww8, sc/source/filter/excel,
sd/source/filter/ppt + filter/source/msfilter/svdfppt.cxx; each
package comment names the files it mirrors). The result then goes
through the ordinary docx / xlsx / pptx reader, so a legacy file
shows what the .docx / .xlsx / .pptx Office would have saved from
it does, and every improvement to an OOXML reader helps both.
doc.Parse / xls.Parse / ppt.Parse do both steps.office.ReadNativeFile (behind office.loadDocument and
the WebAssembly documentLoad) recognises a legacy file by content
(office.LegacyApp: a WordDocument, Workbook / Book or
PowerPoint Document stream), converts it, and imports the OOXML like
any file from another program. A legacy file of another kind throws
("this Excel 97-2003 workbook does not open as a document").cfg.legacyExtensions; OfficeApp (common/office.js) routes them
through OfficePlatform.documentLoad like the app's own format but
treats the result as an import: the document is not attached to the
old file, the status bar says "Imported x.doc - use Save to store it as
.docx", and Save asks where to put the .docx. Like binaryImporters,
this needs OfficePlatform.canConvert(). platform.js maps the legacy
extensions onto their app (nativeOf), and init.agi registers them as
file associations, so a double-click on a .doc opens Docs.office.loadDocument, office.docToDocument /
xlsToWorkbook / pptToPresentation return a bare body, and
office.convertLegacy(src, dest) writes a plain .docx / .xlsx /
.pptx file.testdata/ (made with
Office 2007, author fields scrubbed) and table tests for the record
parsers; formats_test.go covers sniffing and the open path. To check
fidelity, save the same file from Office as OOXML and compare: the
conversion of a .doc should parse to the same body as Office's own
.docx of it..xls, animations and media of
.ppt, and drawn shapes without a picture in .doc are dropped. A
.ppt table arrives as grouped cell shapes, as PowerPoint stores it.A PDF comes into Docs as an editable document, never as pictures of its pages: real text in paragraphs that re-wrap, headings, lists, tables and pictures the user can move or delete. A PDF stores none of that structure - only glyphs at positions - so it is rebuilt from the geometry, the way Word's PDF Reflow does. It all runs in the browser, so it works the same in ArozOS, the web edition and the desktop shell.
cfg.importFormats, see CONTRACT.md): File >
Import lists the formats an app reads but never writes. What one
produces is a new document named after the file (report.pdf opens
as report.docx), attached to nothing: Save asks where to put the
.docx and never offers to write over the PDF, because an import is not
an open. A PDF reached any other way - Open recent, a drop on the web
edition, the open-with hash - takes the same path (openPath routes the
extension). .pdf is deliberately not a Docs file association: a
double-click on a PDF still opens the PDF viewer.common/pdfread.js, OfficePdfRead):
pdf.js 2.7 (common/lib/pdfjs/, Apache-2.0, loaded on first use - it is
several MB) parses the file, and the page's operator list is walked
here with the graphics and text state a PDF reader keeps (CTM, text
matrix, Tc / Tw / Tz / Ts, fill and stroke colour, clip box), so every
run of text comes out with its font, size, colour and position, every
picture as a canvas drawn through its own matrix (rotation, flips and the
clip applied) and every path as a shape. getTextContent() would be
simpler but carries no colour. Two pdf.js traps are handled there: a
font is only resolved once the browser has loaded its face, after the
operator list arrives (fontsReady waits for every font the page sets),
and every font pdf.js draws with one system face shares that face's
loadedName (Helvetica and Helvetica-Bold alike), so fonts are keyed by
their own reference. Font names are turned into families
(ABCDEF+TimesNewRomanPS-BoldMT -> Times New Roman), and symbol-font
bullets into the characters they draw.docs/docs_pdfimport.js,
DocsPdfImport), per page then over the whole document:
<hr>) and
drawings; a cluster of drawings with little text in it is a
figure, rendered as one picture of that region; a small dot or
square just left of a line is a bullet;data-tabs),
and in a fixed-pitch font a gap is that many spaces
(white-space:pre-wrap), so code keeps its alignment;padding-top, from the baselines
and the editor's own line box) and line spacing (data-ls, against
the document's own, measured with DocsLayout.fontRatios) follow;1. a) (iv) 1、),
read across runs, nested by where markers or text line up, as
ul/ol.doc-list with the PDF's own marker and hanging indent;OfficePlatform.blobToSrc like a
dropped-in picture (the window's working copies in ArozOS, inline in the
web edition), one copy per distinct picture (a content hash), JPEG for
opaque pictures and PNG for transparent ones and for rendered figures.
They are encoded with toDataURL: toBlob's callback can take a second
to come back, which over a document of pictures is minutes.node web/Office/docs/test_pdfimport.js builds pages out of
runs and checks lines, paragraphs, lists, tables, columns and running
footers. For fidelity, import real PDFs and compare page by page with
the source (which text starts each page; the reference set in
/reference has Google Docs exports next to their .docx).Every conversion runs through mod/office (server side, or WebAssembly in
the web edition), except things only a browser can compute, which the
client adds to the body first (cfg.prepareNative, also used by the ODF
exports):
props.png) because native
PowerPoint charts are not written yet; cached per chart and uploaded
once, so an unchanged chart costs nothing on the next save.data-export-src, which the writers prefer. Every other picture stays a
link that the server reads.captureVideoFrame in slides.js) into props.png, cached the same way.cell.a).Core.buildPrintModel() in sheets.js) because formula
evaluation and number formatting live in the client.A Docs page looks the same in the editor, in its PDF and (as far as Word's
model allows) in its .docx, because there is only one layout:
docs/docs_layout.js (DocsLayout) lays the live
editor DOM out the way a word processor does and paginates it: line
heights from real font metrics (fontRatios, measured on a 2048px canvas
— CSS line-height: normal differs per font and per platform), list
numbering, tab stops with leaders, table rules compensated for pixel
snapping, keep-with-next / keep-lines / widow and orphan control,
footnote space at the foot of each page. A page boundary is real in the
DOM: whatever crosses it is split into two elements — a paragraph at a
line, the list or quote around it, a table row cell by cell (a copy of
the row takes the rest of every cell) — and a .doc-autobreak spacer
between the halves carries the second one to the next sheet. Each half is
a box of its own, so borders, shading and cell rules end at the bottom of
their page. The halves are paired by a token (data-split on the head,
data-split-of on the tail, data-pair on the spacer; CSS
.doc-split-head/-tail drops the spacing and rule at the cut and the
marker of a continued list item). Undoing a split moves the tail's content
back and rejoins the divided text node, following the caret through it.
Editing around a cut goes through the same undo: unsplitAtCaret runs
before Backspace/Delete at the edge of a cut and before any key typed over
a selection that spans one, unsplitWithin before a table gains or loses
a row or column, and repairSplits drops what editing left behind (a tail
whose spacer was deleted, a marker copied by Enter). A relayout after
typing starts from the page that was edited. Nothing it adds is saved:
stripLayoutArtifacts() in docs.js undoes every split and removes every
spacer and computed attribute before a body is serialized (the paste
sanitizer strips them too)..doc-sheet per page in #pageSheets, behind the
transparent #page. The gap between two sheets is empty space, not a
band painted over one long sheet, and since nothing in the flow sits
there, nothing can show through. The status bar's "Page N of M"
follows the caret, or the middle of the view after a scroll.docs/docs_pdf.js (DocsPdf) reads each sheet of that
DOM: text runs at the browser's baselines, fills and borders (a collapsed
table rule at the width the document states), pictures with their crop,
list markers (a disc/ring/square bullet becomes the shape at the glyph's
measured ink box — the only face shipped with the glyph is a CJK one,
twice the size), tab leaders and the footnote rule. The export does not
hold the editor. The page is only held while it is measured (a few
hundred ms for 90 pages, in its export state); what to draw is written
down as a plain-data display list, and
common/pdfworker.js assembles the file with
common/pdfdraw.js in a Web Worker — embedding and
deflating pictures, subsetting fonts and serializing is where the time
goes (on the 92-page reference it held the page for ~14s before). The
same pdfdraw.js runs in the page when a worker cannot be started.
Progress shows in OfficeApp.showProgress, as in Slides, and the
document can be edited meanwhile without changing the file that comes
out. The PDF always gets an outline (bookmarks) of the headings,
whether or not the document has a table of contents: the same headings
tocEntries() would list, at all six levels (the Title paragraph is no
heading), measured in the export state and written by pdfdraw.js
(job.outline, nested by level, each opening its page at the heading's
top). The other PDFs have one too: Slides lists every slide by its title
placeholder, else "Slide N" (slideOutline in slides/slides_pdf.js),
Sheets every sheet by name, and the server-side Docs exporter the same
headings (both in mod/office/pdf). Font resolution against the shipped Noto faces, text runs and the
raster fallback live in common/pdfcore.js, also
used by Slides. docs/backend/convert.agi's export-pdf and
mod/office/pdf/document.go remain for AGI callers (office.documentToPdf),
but the editor no longer uses them.page.columns > 1) paginate the same way. Before each
layout, every run of text between two full-width blocks (.col-span-all,
a page break) is wrapped in a layout-only div.doc-colsec that carries
the CSS columns (--doc-cols, --doc-colgap on #editor). A section
that fits its page balances; one that runs past the page bottom is given
the height that is left and filled column by column
(.doc-colsec-fill), and splitColumns finds the first content that
spilled into a column past the last one (columnOverflow: a paragraph at
that character, a table at that row) and cuts there - so the copy of the
section carries the rest to the next page like any other split.
Sections are unwrapped with the spacers on everything saved. A columned
document is always laid out whole (no incremental relayout), which is
fine for the short papers the layout is for.Check changes against real documents: the round trip docx → editor → PDF
was tuned against Google Docs' own PDF exports; comparing text line
positions page by page (PyMuPDF on the PDF, getClientRects() on the DOM)
finds a regression in minutes where eyeballing takes hours.
Sheets exports PDF on the server; Docs and Slides do not. Slides'
exporter is slides/slides_pdf.js (SlidesPdf),
built on the vendored pdf-lib, and it runs against the very DOM the
editor is showing.
It draws each slide onto a recording, not a PDF:
OfficePdfDraw.recorder() (common/pdfdraw.js)
hands it stand-ins for pdf-lib's page, whose calls (drawText,
drawImage, pushOperators, ...) are written down as data - operator
arguments as the text they put in the content stream, fonts by the file
they come from (the fonts are still parsed in the page, for their glyph
widths), pictures by source. OfficePdfDraw.run() replays the recording
in the same Web Worker Docs uses, where the pictures are embedded and
deflated, the fonts subset and the file written. On a 30-slide deck of
large pictures that is the difference between an 11s freeze and a longest
stall of about a tenth of a second; the drawing code itself did not change.
The reason is that a slide's appearance is decided by the browser: which
font it resolved out of a stack, where each line wrapped, how tall each
line box came out. A server-side renderer has to re-derive all of that and
the derivations drift — the symptom was a CJK deck exporting as rows of
dots, because fpdf's core fonts are cp1252 and the layout had been
guessed in Helvetica anyway.
Every element goes in as the PDF object it should be:
| element | becomes |
|---|---|
| text | real Tj text, one show-text per line fragment, at the baseline the browser laid it out on |
| image | the original JPEG/PNG bytes, embedded once and re-used |
| crop / shaped crop / rounded corners | a real PDF clip path (shapePathOps, from the same SlidesShapes geometry the canvas draws) |
| flip | a negative scale in the transformation matrix |
| transparency | an ExtGState with /ca |
| re-colour, brightness, contrast | the picture re-encoded through a canvas — a pixel operation in any renderer |
| shape | a real vector path from the catalogue, filled and stroked (even-odd where the shape has holes; stroked only, where it is a brace or a bracket) |
| line | a real vector polyline, arrow heads as filled triangles |
| table | real vector cell fills and rules, plus text |
| chart | the chart's own SVG, translated element by element into PDF vectors |
| rotation | one matrix about the object's centre, with the element measured unrotated |
The font rule, and the one fallback. A PDF can only show text in a font
it carries, and a browser will not hand over the bytes of a system font.
Three answers, tried in that order, per character (resolveChar):
document.fonts.check() answers "is it
loaded" and says yes to any name, so haveFamily probes widths against
two generics instead — installed means different from either one,
because a family can be a generic's own default (Consolas is Chrome's
monospace on Windows, Times New Roman its serif).common/fonts, see
the note there) — fetched, parsed for glyph
coverage, and embedded subset to the glyphs the deck actually used. This
is what carries CJK. In ArozOS a family of the system font library
(System Settings > System Fonts) counts as shipped too: OfficeFonts
loads /system/fonts/faces (login only; only admins upload), declares
every face from its WOFF2 slices, lists the families under "System
fonts" in every font picker, and faceFor hands out the whole font
(/SystemAO/locale/fonts/file/<key>.ttf) when its licence allows
embedding. A variable face is named at the instance wanted
(…ttf#wght=700): the exporter's fontkit builds that instance
(OfficePdfDraw.variationKit), since the stored outlines are only the
default — Chiron GoRound TC's is ExtraLight. A shipped family name wins
over a library family of the same name (Noto Sans TC). The server pads a
font whose glyphs are stored at odd lengths: fontkit's subsetter misplaces
every glyph after the first one of those.planRun / rasterText in pdfcore.js), drawn by the
page's own canvas so the picture is set in the page's fonts. The text
around them stays text. (This used to rasterize the whole text box or
table; see the next point for why that mattered so much.)Characters that draw nothing — zero-width spaces and joiners, direction
marks, variation selectors, a soft hyphen (ignorableCp) — are never
offered to a font at all. The importers write a zero-width space into every
empty line to give it its height, so before this rule a text box or table
with one blank line went to the PDF as a picture of itself, cropped to its
stored frame.
What the browser does to text when it paints has to be repeated, because
the DOM does not show it: text-transform (an all-caps title is "Agenda"
in its text node), letter-spacing (character spacing Tc, after every
character as CSS adds it), and synthetic bold and italic for a shipped
face without that style (the CJK faces ship Regular only). How much a
browser emboldens or slants is its own choice — Chrome strokes the outline
by 1/24 to 1/32 of the size and slants by 1/4, Firefox smears sideways —
so synthStyle measures it on a canvas: the requested weight against
regular-weight text filled and stroked with a growing pen (text rendering
mode 2, what the PDF does) until the ink matches, and the slant from how
far the ink's centre moves per unit of its height. In Chrome that lands on
Skia's own figure at every size; a browser that does not synthesize
measures as nothing, and the PDF follows it.
A system font that is none of the above stands in as the nearest face of
its kind (standIn): for a family this machine lacks, the face the screen
drew it in (OfficeFonts.substituteOf); for an installed one, its shipped
metric twin (Calibri → Carlito), else Cousine for any monospace family,
else the standard font of its kind. The stand-in is drawn at the size that
gives it the original's average advance (OfficeFonts.widthOf), so Cousine
for Consolas is set at 0.917 of the size — Consolas's width and nearly its
x-height — instead of being squeezed to width alone. A monospace family has
to stay monospace: a code listing lines its columns up on one fixed
advance, and a proportional face fitted to whole fragments put gaps after
every syntax-coloured run. Any other installed family is stepped over, and
the character lands on the shipped face the document's own font stack
names next — what the browser does when a font has no glyph, which is why
OfficeFonts.stack() is on the end of every font-family the editor writes.
Because a stand-in is not the face the line was measured in, the ink of
each fragment is then fitted to the place and width the browser gave it
(planRun measures the fragment without the spaces at its ends, which a
stand-in sets at another width; Tz does the squeeze), so it cannot push
the rest of the line out of shape; when the face is the one the browser
used, the ratio is 1 and nothing happens. Spaces in a highlighted span are
still drawn as their highlight box.
Three things about placing the text that are easy to get wrong, and were:
measureText
reports the ascent and descent the browser resolved for a font stack —
the very numbers it laid the text out with. Font files state metrics that
browsers do not always use, and a system font states nothing we can read.Range.getClientRects() returns the content box, not the line box:
ascent plus descent tall, not line-height tall. The baseline is an
ascent below the top of that rect. Treating it as the line box puts every
line a couple of pixels high at 30px type.getBoundingClientRect() takes both in. Measured that way the first
character of every wrapped line sits on the line before, and the export
showed "Basics of R" / "everse Proxy", the next line indented by one
character. So ranges are measured with OfficePdfCore.rangeBox, the
union of the rects that have width, never with the bounding box
(node web/Office/common/test_pdfcore.js pins it).When a whole object does have to be rasterized (only a chart whose SVG the
translator cannot express, now), the picture is taken through an SVG
<foreignObject>, so the browser lays it out and paints it, over the
area the object actually paints — its own box plus anything that overflows
it (paintedBoxOf), since objects do not clip. An SVG image cannot use the
page's web fonts, which is why text never goes this way any more. html2canvas
was tried first and is wrong for this: it re-implements layout over a
clone, and on mixed CJK/Latin text with pre-wrap it breaks lines
somewhere the browser did not — exactly the drift this rework removes. It
survives only as a last resort for the case where even the foreignObject
route fails, because a wrong element beats a missing one. Two things that
route needs and that are easy to get wrong: the computed styles have to be
inlined onto the clone (an SVG image cannot reach the page's stylesheets),
and the markup must be serialized with XMLSerializer — innerHTML
writes <br> unclosed, which is not well-formed XML and makes the whole
element vanish.
Why the slide surface has its own font. .sl-slidebase sets
Arial, "Liberation Sans", Helvetica, "Noto Sans", "Noto Sans TC",
"Noto Sans SC", "Noto Sans JP", "Noto Sans KR", sans-serif instead of
inheriting the app's UI font. A deck must not change shape depending on
which OS the editor runs on; the first three are metrically identical to
each other and to PDF's Helvetica, and the shipped faces behind them carry
everything those three have no glyph for. Keep that list in step with
OfficeFonts.FALLBACK. Text that states its own font (anything imported)
overrides it and goes through OfficeFonts.stack(), which puts the same
tail back on — including on the Go side, where fonts.StackFor
(mod/office/pptx/text.go) appends shippedFontFallbacks to every stack
an import writes.
Only faces that are drawn with may be embedded. The embedder subsets a
font down to the glyphs asked of it, and a subset of no glyphs is not a
font any more — a CFF one fails outright on save. So prepareFonts loads
faces for coverage first, then walks the slide object by object making the
real raster-or-text decision, and embeds only what will actually be drawn.
The bytes are written through OfficePlatform.writeBytes, which base64s
them down the same oversized-payload path every export uses and lands in
common/backend/binsaver.agi → office.writeBinaryFile. In the standalone
web edition it is a download, which means PDF export now works there
too — it no longer needs a backend. Rendering does not block the editor:
File > Export puts a small progress panel in the corner of the canvas
(OfficeApp.showProgress) and works from a snapshot of the deck, so
carrying on editing cannot change the file that comes out.
/reference at the repository root holds real decks and documents next to
the PDF their own application made of them (PowerPoint's Print to PDF,
Google Docs' export). The import and the editors were tuned against them by
rendering each slide or page in the real editor (headless Chrome), cropping
the PDF to the same box and diffing; for text, comparing baselines (PyMuPDF
on the PDF, Range.getClientRects() on the DOM) finds a rule in minutes.
What that turned up, and the code that now follows it:
1.2 × ascent / (ascent + descent) of it. CSS centres the font's
ascent + descent instead, so under the PowerPoint line model
(OfficeFonts.substitute(..., {lines: "powerpoint"})) a font's ascent and
descent are restated to add up to 1.2 em; a paragraph at any other
spacing is moved by the constant difference that leaves
(ascentRatio in pptx/fonts.go, kept in step with METRICS).OfficeFonts.substitute,
see CONTRACT.md): Noto Sans is 16% wider than Calibri and 20% wider than
Garamond, which is what made imported text overflow its boxes. Calibri is
drawn in the shipped Carlito, its metric twin, so its lines break
where Office breaks them; a scaled look-alike only gets the average width
right. PowerPoint wraps exactly at the box's content edge (a PDF line that
seems to run past it ends in the trailing space) and draws no standard
ligatures, so neither do the editors nor the PDF exporter.normAutofit fontScale is drawn as whole points: 20 pt at 92.5% is
19 pt (the reader rounds; the stored scale is only PowerPoint's cache).spcFirstLastPara turns on the first paragraph's space before.pptx.Build writes picture frame fills,
spcFirstLastPara (the stored HTML states every paragraph's spacing as
drawn) and, for a table that came with a style, PowerPoint's built-in
"No Style, No Grid" id with the rules and fills on the cells - so a
re-import, or PowerPoint, draws what the editor showed.l, Symbol ·) and Symbol-font text
come in as the Unicode characters they draw (symbolBullet,
symbolText), in characters the shipped faces carry; an auto-number is
never set in a symbol font.bgRef styles) may
be pictures or gradients (pptx/fill.go); shapes and picture frames may
have gradient and translucent fills; a picture-filled shape is a picture
in that outline.pptx/table.go) and keep merged
cells and per-cell anchoring. SmartArt is read from the drawing
PowerPoint stores with it. Custom geometry is kept as its paths
(pptx/custgeom.go). Office math keeps PowerPoint's fallback picture
unless the formula is a line of symbols, which stays text.palt); a page number with no
stored result is still a page number; a merged table cell crossing a page
cut is split with the table (splitRowspans in docs_layout.js).New slide is a split button on the ribbon (Home and Insert): its icon adds
one, the label under it (a separate button) opens showLayoutPicker() — every layout in LAYOUTS as a
preview of itself. The previews are built by the same newSlide() and
renderSlideContent() the document uses, at the scale the rail uses, so a
preview cannot come to disagree with the slide choosing it makes. The
previews outline every box (.sl-layoutpick-mini .sl-obj),
stated at slide scale so the transform brings it down to a hairline -
without it a layout is a few grey smudges and one looks like the next.
A layout's text boxes are placeholders, as in Google Slides. newPh()
makes them empty, with props.ph saying what they are for (title,
subtitle or body). Any empty text box - a placeholder, a text box left
empty, an emptied one, an empty placeholder from a .pptx - shows a prompt
("Click to add title", PH_PROMPTS) in its own text style and a thin grey
frame (isBlankText() decides, renderObjectEl adds .sl-empty and a
.sl-ph sibling of the text). A single click on one goes straight into
editing. Only surfaces marked .sl-showph show the prompt (the canvas, the
rail, the slide sorter, the layout picker) and .sl-phframe the frame (the
canvas and the picker), so present mode, print and every export draw an
empty box as nothing. The .pptx writer turns ph back into a <p:ph>
(an empty one keeps its size on an a:endParaRPr), so PowerPoint prompts
in it too, and the reader sets ph from the placeholders it imports.
Delete belongs to whatever has the keyboard. A thumbnail takes focus
when it is clicked, and focusing one selects it, so the slide the keyboard
is on and the slide being edited are never two different slides. Delete
then removes the slide; with the canvas focused the same key removes the
selected objects. Both are registered with HK and guarded by
railFocused(), so neither has to know about the other.
Lines look the way Google Slides lets you make them. When a line, a
shape or a picture is selected the Shape Format / Picture Format ribbon tab
(and Home > Drawing) offers Line weight (1-24px) and
Line dash (solid, dot, dash, dash-dot, long dash, long dash-dot); for a line
also Line start and Line end (none, arrow, filled arrow / circle / square /
diamond and open versions of the last four). Each menu pictures its choices.
All of it lives in slides/slides_lines.js
(SlidesLines): the catalogue, the dash patterns (PowerPoint's own presets
in multiples of the weight, flat-capped as PowerPoint draws them) and one
geometry() that turns a polyline into the stroke plus its end marks. The
canvas and the PDF exporter both draw from it, so they cannot disagree. The
props are dashStyle, startHead and endHead; a document from before
them says dash / arrowEnd / arrowStart, which still draw exactly as they
did, and setDash / setHead keep those flags in step for older readers.
The .pptx mapping is mod/office/pptx/lines.go.
A callout's tip is an adjustment, as in PowerPoint. The four speech
bubbles (wedgeRectCallout, wedgeRoundRectCallout, wedgeEllipseCallout,
cloudCallout) carry props.adj with PresentationML's own names and scale
(adj1/adj2 place the tip at centre + adj x frame, in 1/100000;
adj3 rounds the rounded one's corners). SlidesShapes.path(kind, w, h, adj)
draws them with PowerPoint's formulas - the body fills the frame, the tail
leaves the side the tip lies beyond - and a selected callout shows a yellow
diamond on its tip to drag; a rounded rectangle shows one where its corner
ends. A callout made before adjustments existed has no adj and keeps its old
drawing (body in the top 72%, tip at the bottom) until its handle is first
dragged, when the frame shrinks to the body and the tip is stated where it
already was (adoptAdjustments); the .pptx writer converts it the same way
(mod/office/pptx/adjust.go).
Every preset with a feature to tune has its handles too - one yellow
diamond per adjustment (adjHandles in slides.js, geometry in
SlidesShapes.handles / dragHandle): the snipped and rounded rectangles,
the polygons PowerPoint adjusts, frame, half frame, L shape, diagonal stripe,
plaque, can, cube, bevel, donut, "no" symbol, teardrop, moon, sun, smiley,
folded corner, pie / chord / arc / block arc (their angles, round the
ellipse), every block, bent, U-turn, curved, circular and striped arrow,
the arrow callouts, the stars, the waves, the brackets and braces and the
equation shapes. Those all draw to PowerPoint's own formulas
(presetShapeDefinitions), angles and arcTo included, so a reshaped
shape opens in PowerPoint as it looks here. Only the ribbons and the
scrolls still draw at fixed proportions. A picture cropped to one of those
shapes gets the same handles - its props.adj belongs to its mask, goes
into the clip path and the PDF clip, and is written to the picture's
prstGeom - and one cropped to a rounded rectangle (or imported with
rounded corners) gets the radius handle. Dragging one redraws only that
object (refreshObjEl). Every object the pointer would move when dragged
shows the move cursor; an object being edited shows the caret instead.
Every shape the editor draws lives in
slides/slides_shapes.js (SlidesShapes) as
geometry — about 130 of them, in the four groups the Insert > Shape picker
offers: shapes, arrows, call outs and equation.
They are named after the PresentationML presets they are (rightBrace,
flowChartDecision, wedgeRoundRectCallout). That is the point of the
file: an imported deck keeps its own vocabulary, and
prstToShapeKind / shapeKindPrst (mod/office/pptx/{reader,writer}.go)
are a lookup rather than a translation. The editor had three names of its
own before the catalogue — round, arrow, star — and they are gone:
SlidesShapes.ALIASES knows what they used to mean and normalizeBody()
runs every kind through canonical() as a document loads, so a deck
written back then is rewritten the first time it is opened. The Go writer
keeps the same three for a deck that has not been through the editor yet. A preset the catalogue does not draw is sent to the nearest outline
that it does, and only a completely unknown one becomes a rectangle. The symptom
that prompted all this was a rightBrace importing as a thin outlined
rectangle, rotated — two long diagonal lines where a brace should be.
Every shape produces an SVG path using only M, L, C and Z. Arcs are
converted to cubics once, by Path.arc(), so nothing downstream has to
understand an arc flag — and three things get to share one geometry:
shapeSvg in slides.js),clip-path: path(...), which is how a picture is cropped to a shape, andsvgPathOps) is about fifteen lines
because that is all it has to parse.Three flags on a catalogue entry change how it is drawn, and all three
paths honour them: open (a brace, a bracket, an arc — a line and not an
area, so it is stroked and never filled, and gets a stroke of its own if the
document did not give it one), evenOdd (the path has holes in it), and
detail (markings such as the divider bars of a predefined process, drawn
over the outline rather than filled).
Picking a shape arms the canvas (insertShape -> pendingDraw = "shape"), as
PowerPoint does: drag out its box (Shift keeps the catalogue's proportions,
defaultSize), or click to drop it at that size. Lines, likewise, are hit by
their stroke only - the line's box lets clicks through (slides.css,
.sl-type-line), so a click beside a diagonal reaches what is under it.
The picker itself is showShapePicker(): the categories down the left, the
shapes of the one in hand as icons on the right. The icons come from
SlidesShapes.icon() — the same geometry again — so a picker entry cannot
come to disagree with what choosing it inserts.
MASK_KINDS is deliberately not the whole catalogue: a shaped crop reads
as a silhouette, so the crop-shape grid offers the couple of dozen outlines
that still say something at thumbnail size.
Cropping never touches the pixels. The object frame says which part of the
picture is visible and props.crop says which part of the source that is —
the same definition PowerPoint's srcRect uses, so a crop made in the
editor and one made in PowerPoint are interchangeable. fullImageRect()
in slides.js inverts the pair to find where the whole picture sits, and
that is the whole of the crop tool's geometry.
The tools live in slides/slides_image.js
(SlidesImageTools) and reach the document only through a host object of
callbacks, so slides.js stays about the document and the canvas. They are
reachable three ways: a floating picture bar under the selected image
(the text-edit bar's chrome, so the two feel like one family), the Picture
Format ribbon tab, and the picture's context menu.
SlidesShapes.icon() from the same
geometry the canvas uses so an icon cannot drift from the mask it
applies. Picking one sets props.mask, drawn as a clip-path and written
to .pptx as a prstGeom on the picture.#slFormatPanel, docked right of the canvas:
size, rotation and flips, position and align-to-slide, re-colour, and the
brightness / contrast / transparency adjustments. imageFilter() is the
single place that turns recolor + bright + contrast into a CSS
filter, so the canvas, the thumbnails, present mode and the panel's own
swatches cannot disagree — the swatches show the picture itself through
each filter, so the preview is the result.props.orig — stamped the first time a picture is trimmed, and holding the
frame the whole picture filled — and corrects the height to the source's
own aspect ratio, so a picture stretched by dragging a corner comes back
undistorted too.The colour work round-trips through .pptx as the DrawingML effects on the
picture's <a:blip>: a:alphaModFix for transparency, a:grayscl /
a:biLevel / a:duotone for the re-colour preset, and a:lum for
brightness and contrast. The one preset with no DrawingML equivalent is
Negative, which is written as no effect rather than as something else.
sheets/formula.js is a DOM-free tokenizer, parser,
evaluator and calculator that also runs under Node. The functions themselves
(377 of them) live in modules that register into it and load after it, in
this order, from sheets/index.html:
| File | Functions |
|---|---|
formula_fn_logic.js |
logical, IS*/info, operator functions (ADD, EQ, …) |
formula_fn_math.js |
rounding, powers/logs, trig, integers, number bases, bits, CONVERT |
formula_fn_stats.js |
aggregates, *IF/*IFS, SUBTOTAL, D*, descriptive stats, regression |
formula_fn_text.js |
text, TEXT (via numfmt.js), regex, ROMAN, double-byte (LENB …) |
formula_fn_date.js |
dates, times, working days, YEARFRAC, DAYS360 |
formula_fn_lookup.js |
VLOOKUP MATCH XMATCH XLOOKUP INDEX LOOKUP ROW … |
formula_fn_ref.js |
OFFSET INDIRECT ADDRESS CELL SHEET(S) HYPERLINK TO_* |
formula_fn_array.js |
FILTER SORT UNIQUE SEQUENCE SPLIT stacking, MMULT, LINEST … |
formula_fn_finance.js |
loans, NPV/IRR/XIRR, depreciation |
formula_node.js loads the same set under Node.
FUNCTION_PLAN.md tracks what is done and what is
next.
node web/Office/sheets/test_formula.js # engine: parser, refs, arrays, rewriting
node web/Office/sheets/test_formula_fns.js # every function, against Excel's documented examples
test_formula_fns.js fails when a registered function has no test, so a new
function always comes with one.
Copy and paste between sheets. A copy of Sheets cells remembers its
source sheet and the computed value of every cell. Ctrl+V onto another sheet
defaults to Keep source links: formulas get their plain references pinned
to the source sheet (F.qualifyRefs: =E13*B2 becomes
=SheetA!E13*SheetA!B2), so they still show the source results. On the same
sheet, formulas shift relative to where they land, as before. A cut moves the
cells, so their formulas keep pointing where they did. The other modes
(values, values with formatting, formatting only, paste link, transpose) are
listed in the paste-options button at the corner of the pasted block, in Edit
and in the right-click menu (> Paste special), and values only is also on
Ctrl+Shift+V (PASTE_MODES / pasteInternal(mode) in sheets.js).
Function suggestions. Typing a function name in a formula (=AVE) opens
a popup (sheets_suggest.js, SheetFnSuggest)
on the cell editor and the formula bar; the highlighted entry shows a
description, the usage line (spec.syntax) and an example. Descriptions and
examples live in formula_help.js
(SheetFormulaHelp), and test_formula.js fails when a function has no
entry there or its example does not parse.
Adding a function. Register it in the matching module:
def("NAME", minArgs, maxArgs, function (args, E, arrayCtx) { ... },
{ elem: true, syntax: "NAME(value)" });
args are AST nodes, evaluated through the helper object E: E.num,
E.int, E.str, E.bool, E.val (scalars with defaults for omitted
arguments), E.arr/E.flat (ranges and arrays), E.numbers(args, mode)
(the spreadsheet rules for "all the numbers in these arguments": "sum"
skips text in cells but rejects typed text, "a" counts text as 0),
E.criteria(value) (the COUNTIF matcher: ">5", "a*", "<>", dates),
E.self (the cell being evaluated), E.raw / E.rowState / E.format
(source text, hidden/filtered rows, number format). Return a value, an
F.Arr, or an FErr. elem: true marks a scalar function, which the engine
then applies element by element inside SUMPRODUCT, SUM(...) and other
array contexts (SUMPRODUCT(LEN(A1:A9))). Excel's _xlfn. / _xlws. name
prefixes are ignored when calling, stripped by the xlsx reader and written
back for functions listed in xlFutureFunctions
(mod/office/xlsx/formula.go) — add new
post-2007 Excel functions there too.
Date text ("2024-05-01", "5/1/2024", "1 May 2024", "13:30") is read as
a date serial wherever a number is expected, as in Excel.
References as values. OFFSET, INDIRECT and INDEX answer with a
reference (F.Ref), not just a value, so they can be used wherever a range
can: SUM(OFFSET(A1,0,0,10,1)), and : joins them
(A1:INDEX(B1:B9,3), SUM(A1:INDIRECT("B5"))). Take one with E.ref(node)
and build one with E.makeRef(...); a reference covering one cell reads as
that cell's value.
Whole columns and rows. A:B, 2:5 and the Sheets-style A2:A fill the
missing coordinate from the sheet's used range (opts.bounds, cached per
recalculation in sheets.js), so they cost what the data costs, not what the
grid could hold.
Array literals. {1,2;3,4} is two rows of two, usable anywhere an array
is: SUM({1,2,3}), VLOOKUP(2,{1,"a";2,"b"},2,FALSE).
Defined names. body.names is [{name, formula, sheet?}] (sheet = the
index a sheet-local name belongs to). The calculator resolves a name once per
recalculation, in the scope of the sheet that defines it, and usually to a
reference - so SUM(Sales) works like SUM(Data!B2:B99). Data > Named
ranges (and Formulas > Name manager) manages them, renaming a sheet rewrites them, and they round-trip
through xlsx <definedNames> (Excel's own _xlnm.* entries are skipped:
print areas and filter ranges belong to features modelled elsewhere).
Spilling (dynamic arrays). A formula whose result is several cells
(=FILTER(...), =SORT(A2:C9), =B2:B9*2, =SEQUENCE(10)) fills the cells
to its right and below. Those cells stay empty in the model: the calculator
answers their values from the anchor. Rules and machinery:
maySpill):
ranges, array literals and names produce arrays; operators and elem
functions pass them through; a function is array: true (or a function of
its argument nodes, as INDEX/XLOOKUP/ROW do), or passthrough: true
when it returns one of its arguments (IF, CHOOSE, IFERROR ...).
Only those formulas are evaluated in array context, so everything else
keeps its exact old behaviour (the Helpdesk golden file is unchanged).
A cheap text pre-filter (a : { @, an array function name or a
defined name) keeps the check off plain formulas.opts.formulaCells) and records
what each covers, so later reads are a map lookup.#SPILL! with a message naming the cell; typing into a spilled
cell does exactly that. Spilled cells wear the anchor hint (dates stay
dates).calc.spillAt(col,row,sheet) gives the spill a cell belongs to (the grid
draws a dashed outline and shows the anchor formula greyed in the formula
bar); calc.spillList(sheet) lists them (the grid grows to fit).@A1:A9 / SINGLE(...) is implicit intersection; ARRAYFORMULA(x)
evaluates x as an array.Core.exportBody() tags each anchor with a = the range it fills,
and the writer emits <f t="array" ref="..."> with cm="1" plus the
xl/metadata.xml dynamic-array part, so Excel sees real dynamic arrays
(ARRAYFORMULA(x) is written as a dynamic-array x). On import, the
cached results inside an array formula's range are dropped so they do not
block the spill. FILTER/SORT get Excel's _xlfn._xlws. prefix.A1#), and whole-column refs do
not see spilled rows past the last typed cell.Result hints. A function may ask for the number format its cell should
wear (spec.hint, or E.hint("date")) or mark the result as a link
(E.link(url), HYPERLINK). The grid applies a hint only when the cell has
no format of its own, so =TODAY() reads as a date while an explicit format
always wins; calc.hintAt(col,row,sheet) reads it back. Evaluate the cell
before asking for its hint - it is recorded while the formula runs.
Golden tests against real files. Save a workbook from Excel or Google Sheets (it stores each formula's computed value), then:
OFFICE_GOLDEN_DIR=/path/to/xlsx go test ./mod/office/xlsx/ -run TestGoldenDump
node web/Office/sheets/test_golden.js /path/to/xlsx
Every formula is recalculated and compared with the stored value (volatile
TODAY/NOW/RAND are skipped). The Helpdesk reference workbook checks
52,111 formulas with no differences.
Cross-sheet references (Data!A1, 'Closed Tickets'!$C$3:$C$5000) are
resolved by one workbook-wide calculator: createCalculator(getRaw, opts)
memoizes per sheet + cell, so switching tabs does not recompute anything, and
every formula reads its unqualified refs from its own sheet. Renaming a sheet
rewrites the formulas that name it (renameSheetRefs); inserting/deleting
rows or moving a range adjusts refs to that sheet from every sheet.
Arrays. Inside SUMPRODUCT (and array expressions handed to SUM & co.)
a range evaluates to an array and operators work element by element with
Excel's broadcasting, which is what report-style workbooks built on
SUMPRODUCT((Data!A2:A5000="x")*(Data!B2:B5000)) need. Ranges are cached as
arrays for the life of a recalc, and so is "cached range compared with a
constant", because such reports repeat the same criteria in every cell. The
reference workbook (1,150 SUMPRODUCT-heavy cells over a 5,000-row sheet of
51k formulas) recalculates in ~1 s cold and matches Excel's cached values in
every cell. A bare range outside an array context is still #VALUE! (no
spilling).
AND/OR follow Excel for text: text inside a referenced cell or range is
skipped, text typed straight into the call is #VALUE!. A blank cell equals
"".
Shared formulas. Excel writes a filled-down formula once
(<f t="shared" ref="K3:K66" si="0">B3-C3</f>) and leaves the other cells
as <f t="shared" si="0"/>. The Go reader expands every follower by moving
the master's relative refs (mod/office/xlsx/formula.go), so they stay live
formulas instead of frozen cached values.
Two deliberate departures from Excel, both matching Sheets:
IF's value_if_false is optional and blank when omitted. Excel
answers FALSE, which put a stray "FALSE" in the cell for the very common
=IF(A2="foo","A2 is foo") shape.="Google"="google"
is true and VLOOKUP("oRaNgE", ...) finds Orange.VLOOKUP/HLOOKUP default to the approximate ("is_sorted") mode. Excel and
Sheets binary-search there, which returns arbitrary answers on unsorted data;
this scans and keeps the best match at or below the key instead — identical
on sorted data, merely imperfect rather than arbitrary on unsorted. FALSE
means exact match, and a miss is #N/A so IFERROR/IFNA can catch it.
REGEX* use JavaScript regular expressions (Google uses RE2; JavaScript
accepts a superset, e.g. lookbehind). (?i) at the start is honoured.
Not implemented yet (see the plan): LET/LAMBDA and the MAP/REDUCE
family, probability distributions, bond maths, complex numbers, and
dependency tracking (any edit resets the memo, so a very heavy workbook
recomputes what is on screen after every change).
sheets/sheets_cf.js (SheetsCF) re-evaluates rules
every time the grid paints. Rule kinds: empty/not-empty, the text tests
(contains, starts/ends with, is exactly), numeric comparisons incl. between,
date before/after/on, and a custom formula.
Rules belong to cells, not to the sheet. cell.cf lists the rule ids a
cell carries and sheet.cfDefs holds the bodies. That is what makes a rule
behave like the rest of a cell's formatting: the panel shows only the rules
on the current selection, and a rule travels on move, copy and fill because
those already move whole cell objects (deep(cell)). Applying to a range
stamps the id onto every cell in it, so range-wide rules are still one
action — including onto empty cells, so a value typed there later is still
formatted. MAX_STAMP caps how many cells one apply may touch.
The id is shared, so editing is copy-on-write: the edit mints a new def
and swaps it onto just the selected cells, leaving other cells that shared
the old rule alone. sweepDefs() drops bodies nothing references.
Ids are used rather than inlining rule objects per cell because snap()
JSON-stringifies the whole body into the undo stack on every commit, 80 deep
— a 1000-cell column rule costs ~27 KB this way instead of well over 100 KB.
Two things make range rules work without a separate rule kind:
$-anchored ones
left alone — so =SUM($B1:$D1)>$E1 tests each row against its own total,
and =SUM($B$1:$D$4)>200 tests one aggregate for the whole block.=AVERAGE($F$2:$F$99)" costs no more
than a plain number.Formulas are compiled once per distinct source and their reference nodes are
rewritten in place before each evaluation (compile / evalAt); re-parsing
per cell was far too slow for a repainting grid.
Rules are first-match-wins per property, like Google Sheets: the topmost
rule that sets a background owns the background, and a later rule can still
contribute a text colour the first left alone. styleAt() stays the cell's
own style (what the toolbar edits and what is saved) while effStyleAt()
layers the matching rule on top — paint and the PDF print model read the
second, everything that edits formatting reads the first, so a rule is never
mistaken for something the user applied by hand.
Rules ride in the document body and reach PDF export through the print
model. The .xlsx holds them as Excel's own conditional formats
(xlsx/cf.go): the cells carrying a rule are
gathered into ranges, the rule's relative references are moved from its
anchor to the range's corner, its look becomes a <dxf>, and the rules are
ranked the way the cells list them - the reader stamps them back onto the
cells. Excel's visual rules (colour scales, data bars, icon sets, top-N)
have no counterpart here and are not read. They are dropped on .ods
export, which would need a style-map writer.
All three apps declare saveFormats (see
common/CONTRACT.md), so a document opened from a
foreign format stays that file: Ctrl+S rewrites it in its own format
instead of forcing a Save As to the app's own format, and File > Save as
offers the whole list (plus PDF, which is one-way).
| App | saved back into | declared in |
|---|---|---|
| Docs | .odt, .html/.htm, .md, .txt (+ .pdf one-way) | SAVE_FORMATS in docs/docs.js |
| Sheets | .ods, .csv, .tsv (+ .pdf one-way) | SAVE_FORMATS in sheets/sheets_io.js |
| Slides | .odp (+ .pdf one-way) | SAVE_FORMATS in slides/slides.js |
Each format vetoes what it cannot hold — .csv/.tsv reject formulas,
charts, notes, merges and second sheets; .ods rejects charts
(odf/ods_writer.go cannot represent them); .odp rejects video and audio
objects (odf/odp_writer.go emits no case for them); every Docs writer but the
.docx rejects comments and pending suggestions, because they are fed
resolvedHtml() and would come back with insertions accepted and deletions
applied; .txt additionally rejects images and tables. The veto lists what
would be lost and offers the app's own format instead, so no save quietly
drops content. Purely visual formatting
is deliberately not a veto reason: it would fire on nearly every CSV edit.
When a format's Go writer gains or loses a capability, update the matching
unsupported().
The banner. Living in a foreign file is the right default — somebody who
opened a .docx wants a .docx back — but it also means every feature that
format cannot hold is dropped on each save. So the framework shows a warning
strip under the toolbar for as long as the open file is not native
(updateForeignBanner in common/office.js, styled
.of-fmtbanner in common/office.css), with the one
click out: Convert to <native ext> asks where to put a native copy,
writes it, and opens it in a window of its own through
OfficePlatform.openDocument — leaving this editor on the original file,
because which of the two to go on working in is the person's call. Native
documents never see any of it, and the strip can be dismissed per file.
All that pre-baking makes the export payload big, and the AGI gateway reads
its POST parameters with Go's r.ParseForm, which drops every parameter
once a urlencoded body passes 10 MB (the connection is then reset
mid-upload and the app can only report "cannot reach the ArozOS backend").
Export calls therefore go through OfficeApp.agirunLarge instead of
ao_module_agirun: under 4 MB it posts normally, above that it uploads the
payload to tmp:/.appdata/Office/tmp/ through the system upload endpoint
(streamed to disk - the host never has to buffer it in RAM, which matters on
low-memory boards) and passes dataFile to the backend script, which reads
and deletes it. Raising the server-side form limit is not an option here.
Opening a large document takes a moment (fetching and unpacking it, a server
or WebAssembly conversion for .docx / .xlsx / .pptx, laying out every
page), so Docs, Sheets and Slides start behind a splash that says what is
happening — common/splash.js,
contract in CONTRACT.md. It is a softly tinted card in the app's colour
with the app icon, "ArozOS Docs/Sheets/Slides", a tagline, loading dots and
the status in the bottom-left corner (any other app gets the suite card: the
ArozOS mark and a progress bar). Its artwork is SVG in
img/splash/ - the icons, the mark, and two corner shapes used
as CSS masks so one file serves every app colour. In a desktop float window
the window opens small (InitFWSize 480x320) and grows to 1080x700, both
centred on the desktop, once the document is on screen; in a browser tab the
same card fills the page and scales with it. Sheets grows to
1180x720 and Slides to 1220x740. Each index.html loads its stylesheets and
scripts in <body>, after the splash, so the splash paints while they arrive.
Selecting a picture shows the contextual Picture Format tab (Crop,
Reset picture, border colour and weight, Wrap text, Align, Size &
properties); the same actions are on the picture's context menu, and a
double click opens Size & properties. Everything is stored the way the
docx reader and writer already speak it (see the comment above
pictureCrop in docs.js): crop as object-view-box: inset(t% r% b% l%)
(DrawingML srcRect), the outline as a CSS border, and wrapping as inline
or img.doc-anchor (block = top and bottom, or a float). Alignment of an
anchored picture is its margin-left, which the writer saves as the
horizontal offset: text-align cannot move a block image, so the Home
align buttons call alignPicture while a picture is selected, and a
centred or right-set picture is placed again whenever its width changes.
selectImage): eight squares and a rotate knob, as in
Google Docs. A corner keeps the frame's shape (Shift stretches freely),
a side stretches one way; the size is the picture's width / height.turnPicture), the
way the .docx import already bakes a quarter turn (docx/picture.go):
the editor has no turned pictures, because a CSS transform would not
move the text around one. The knob previews with a transform and bakes
on release; Picture Format > Rotate and the picture menu turn by 90° and
flip. The result is the turned frame (a PNG with see-through corners
unless it is a quarter turn of a JPEG, which stays a JPEG), and the crop
goes into it. turnSource keeps the first bitmap for the session, so a
second turn draws from it instead of from a copy of a copy.max-width: 100%
narrows a picture in a column or table cell narrower than it, and its
stated height used to squash it. fitPicture gives every picture with a
stated size the matching aspect-ratio, and docs.css lets the height
follow it (height: auto !important); it is for show only and
stripLayoutArtifacts leaves it out of what is saved. When a table
column is narrowed (a border drag, an inserted column) settlePictures
makes the size shown the picture's size, as Google Docs does, so the
files get it too. The .docx writer scales a stated height along when it
clamps a picture to the text column, to match.Insert > Table opens Word's grid as a dropdown under the button
(openTableGrid in docs.js): move over it to size the table, click to
insert, or "Insert table..." under the grid for a size past 10 x 8. The
arrow keys move the size and Enter inserts while it is open.
A table is edited from the right-click menu only, as in Word and
Google Docs: the floating text bar over selected text carries text
formatting and never table commands (Slides still passes tableOps to it
for its own tables). The menu is built from what is under the pointer and
what is selected, and leaves out what does not apply:
| Right-click on | Shows |
|---|---|
| a table cell, or a block of selected cells | the clipboard, Insert (columns left / right, rows above / below) and Delete (columns, rows, table), then header row, banded rows, theme, borders and cell background. No text formatting, page break or Select all. Insert link and Comment only over text inside one cell |
| a picture | the picture's commands and the clipboard |
| a link | Edit link, Open link, Remove link |
| a table of contents | Update table and its options |
| selected text | Comment, the clipboard, Insert link (its formatting is on the floating bar) |
| a caret in running text | Paste, Bold / Italic / Underline / Clear formatting, Insert page break, Select all |
Insert and Delete act on every row or column the selection covers, and
say how many ("Insert 2 rows above"). The cells are found by
cellBlock(): a caret, Chrome's one range across cells, or Firefox's
range per cell. A row the page layout cut in two stands for its first
part (splitHeadCell), and onBlock() makes the table whole with
DocsLayout.unsplitWithin before it counts rows, then lays the pages out
again.
Column widths. A table never resized has no <colgroup>: the
stylesheet shares 100% out equally, however many columns it has. A table
with one (every imported table, and one whose borders were dragged) keeps
its width when columns come or go - colsInserted / colsDeleted rewrite
the colgroup in its own unit (pt from .docx, % from .odt, px after a
drag). Equal columns stay equal. Sized columns keep their proportions on
an insert (the new one starts as wide as its neighbour), and a deleted
column's width goes to the column after it (before it at the right edge),
so the borders the user placed stay put. A border drag converts the
colgroup to px first (ensureColgroup), or an imported table's pt widths
were read as px and the column jumped. The menu icons are Word's (tableInsertLeft ... tableDelete in
common/icons.js, a menu item's svg).
References > Table of contents inserts a "Contents" title and one line
per Heading 1-3 (not the Title): the heading's text, a right tab with a
dot leader at the margin and the page it is on as laid out now. They are
ordinary paragraphs - p.doc-toc (.doc-toc-title for the title,
data-toc-level on an entry, data-toc-max the deepest heading the
table lists when it is not 3) - so the layout, the PDF and every writer
handle them like any text, and nothing new had to be taught to the
paginator: a long table splits across pages like any paragraphs.
drawTocOverlay() in docs.js puts a .doc-toc-frame in #page
(layout px, zoomed with the page) with one box per page the table covers
and an "Update table" tab above the first, while the caret is in the
table (solid) or the mouse is over it (dashed). It is never saved, print
hides it and docs_pdf.js skips it. A table is a run of .doc-toc
paragraphs that follow each other (tocGroups()), so two tables are
updated separately.buildTocPanel,
modelled on Google Docs'): a format card (Plain text, Dotted, Links),
page numbers, the tab leader (dots, dashes, solid line), blue links,
bold top level, and per heading level 1-6 whether it is listed and its
indent in mm (toggling a level resets the indents to 6.35 mm steps from
the top level the document has). The table keeps its look as JSON in
data-toc-cfg on every entry (TOC_DEFAULT lists the keys), so updates
and saves keep it; a table without one gets one read from how its lines
look (tocCfgOf - an imported Google Docs table comes up as Plain text,
bold, Heading 1-6). Every entry links to its heading (an _Toc... id the
editor adds, Word's own bookmark naming), drawn as text unless the table
shows links. The writer turns the levels into \o "from-to" and no page
numbers into \n.mod/office/docx/toc.go)
wraps a table in Word's Table of Contents building-block control
(w:sdt with docPartGallery) and the entries in a
TOC \o "1-3" \h \z \u field, and styles the lines with Word's
TOC Heading / toc 1..9 styles, so Word offers its own Update Table.
The reader maps those styles back to .doc-toc - Word's TOC Heading
is based on Heading 1, so tocLevel is asked before headingLevel
would call the title a heading. Google Docs writes no TOC styles:
its entries are only the result of a TOC \t "Heading 1,1,...Heading
6,6," field, each a link to its heading's bookmark (and its "Table of
Contents" title is a real Heading 3 outside the control, listed in the
table itself). So a paragraph shown inside a TOC field that has text
and a tab or a # link is an entry too; its level comes from the
heading its link points at once the body is read (resolveTocLevels),
and the field's range becomes data-toc-max (an update must not drop
the Heading 4-6 lines). An update indents from the top level present,
so a document whose chapters are Heading 2 still starts at the margin.
ODT has no table of contents element yet (the lines export as text).The header and footer are one editable pair per simulated page: the
editor keeps a copy in every sheet's margin band (layoutHeaderFooters
in docs.js), all of them editable and mirroring each other, so the text
can be changed from any page. They are absolutely positioned on purpose —
an in-flow header ate page-one content and made the preview disagree with
the export about where the first page ends.
Pagination is measured from the live DOM, so it can only be right once the
DOM has its final size: a document opened from disk paginates while its
pictures are still decoding (a fresh <img> measures zero tall until
its load fires), which used to leave the bands and the automatic page
breaks positioned for a much shorter document. watchContentSize() in
docs.js re-runs updatePageGuides() whenever the flow changes height on
its own — image load (captured on #editor, since load does not
bubble), document.fonts.ready, and a ResizeObserver. Keep that hook
alive when touching the boot path.
hfMode maps onto each format's own mechanism:
| mode | preview | DOCX | ODT | |
|---|---|---|---|---|
all |
band on every sheet | header/footer func on every page | header1.xml / footer1.xml |
style:header / style:footer |
except-first |
page one's band hidden | hfOnPage() skips page 1 |
<w:titlePg/> and no first-page part |
empty style:header-first / style:footer-first |
none |
no bands | no header/footer text | no parts written | no header/footer elements |
The page counter (pageNumbers) stays its own page-setup option, except
that a suppressed first page suppresses its number too — the same thing
Word's titlePg does. Browser printing repeats one position: fixed
pair on every sheet (print engines cannot skip page one); PDF export is
the path that honours every mode exactly.
pptx/reader.go +
pptx/text.go / pptx/color.go, odf/odp_reader.go)
resolve, lowest priority first: the presentation's default text style,
the master's txStyles for the placeholder kind, the master's and then
the layout's matching placeholder lstStyle, the shape's own lstStyle,
the paragraph's pPr, the run's rPr — per outline level. Colours go
through the theme's clrScheme and the master's clrMap (that is what
makes tx1 mean dk1 on one deck and lt1 on another), with the
lumMod/lumOff/shade/tint transforms applied. A slide is drawn on
top of its layout's decoration and the master's, minus their
placeholders, which are prototypes rather than content. Skipping any of
this does not merely lose polish — text lands at the wrong size, in the
wrong place, sometimes white on white. pptx_fidelity_test.go pins each
rule with the smallest package that exercises it; the ODF equivalents are
in odf_test.go.1.2 × the stated percentage. PowerPoint's "single"
spacing is the font's line height, so <a:lnSpc><a:spcPct val="115000"/>
is CSS line-height: 1.15 × 1.2. The constant is pptxLineHeightFactor,
checked against Google Slides' own PDF export of a real deck. Two related
traps: a paragraph's block font-size must be its smallest run (it
is a floor under every line box, so a big run would inflate a short line
under it), and an <a:br/> needs a sized zero-width span after it or the
empty line it opens gets no height at all.<p:embeddedFontLst> points
at .fntdata parts, which are EOT wrappers.
pptx/fonts.go unwraps a bare sfnt or
an uncompressed EOT (what PowerPoint writes) into an @font-face data
URL, under a per-face and per-deck size cap so a multi-megabyte CJK face
cannot make a document painful to edit. Google Slides writes
MicroType-Express-compressed EOT, which needs a decompressor far larger
than the rest of this package — those faces are declined and the text
falls back to the CSS stack. That is the one remaining reason an imported
deck can differ visibly from its source: the glyphs are a substitute, so
a line may wrap a word earlier.docx/reader.go,
docx/props.go,
docx/numbering.go): a
paragraph's look is docDefaults → the paragraph style's basedOn chain
→ direct pPr → character style → run rPr. Toggles are tri-state
(<w:b w:val="0"/> switches bold off against a bold style — reading it
as "present = on" is the classic bug). Numbering resolves num →
abstractNum → lvlOverride, with counters per list id.cv.gdocs
branches so a Word document is not bent by them.docx/picture.go): a CSS transform
would not move the text around it, so the frame is swapped and the crop
turned with it, and the picture lays out, prints and saves as it looks.docx/writer.go): docDefaults,
heading styles and editorBlockCSS mirror docs.css (a blockquote's
3px rule and padding, a pre's frame and shading, a th centred), so
the export starts from the editor's defaults and lays the element's own
inline style over them. Paragraph borders use Word's geometry: the text
keeps its indent and the rule is drawn w:space outside it — the reader
maps that back to margin + border + padding. A block inside an indent
container (the browser's indent command wraps paragraphs in a
blockquote style="margin: 0 0 0 40px") takes the container's indent.
Three custom styles mark what Word cannot express, so an import restores
it exactly: ArozPageNumber (the page number the editor draws by itself —
it comes back as pageNumbers, not footer text), ArozHorizontalRule
(an <hr>) and ArozEditorTable (an editor-made table, which keeps its
CSS spacing). The editor's plain 9pt grey header/footer also comes back
plain. A table or picture in a multi-column page is sized to one column.TestDocxRichRoundTrip pins
model → docx → model for each construct; when adding one, add a row. A
mismatch shows up as layout drift the next time the file is opened, not
as an error.pptx/writer.go): embedded media
(a:videoFile + p14:media + timing tree, python-pptx-identical
structure) was implemented and still would not play reliably in
PowerPoint/Google Slides, so the slide shows the captured poster frame as
a plain picture. The media file itself travels in the editor copy the
suite embeds (arozos/assets/), so it plays in Slides. For the AGI
office.presentationToPptx export, pptx.BuildMedia still returns a
sidecar zip of the media that the AGI layer writes next to the pptx.PDF export (pdf/pdf.go /
pdf/document.go /
pdf/sheet.go): built on
github.com/go-pdf/fpdf (MIT). Real selectable text, not screenshots.
Gotchas encoded in pdf/pdf.go / pdf/document.go:
CellFormat does not clip, and the client's column widths do not
survive the font change. The client measures columns in the browser's
UI font and sends CSS pixels; pdf/sheet.go draws the same text in
Helvetica at 9pt, so a value that sat comfortably in its column on
screen can come out slightly wider here — and fpdf happily paints it
straight over the next column (2026-08-24 21:01:2Yami Odymel).
Two layers deal with this, in order:sheetFitColumns() widens each column to its widest cell before
laying out, so the data is shown in full rather than truncated. The
growth is capped (sheetColGrowMax, sheetColPageFrac) so one very
long cell cannot squeeze the rest into slivers. Widening is safe
because widths and the font are then scaled by the same factor.pdfFitText() (pdf/pdf.go) is the backstop for what still cannot fit
— mainly once the font hits its 5pt floor and stops shrinking with
the columns. It trims to the width and marks the cut with an
ellipsis, measuring the translated text but cutting on runes of
the original so multi-byte characters never split.TestSheetPdfCellsNeverOverlap pins the invariant by reading back the
text-drawing operators and asserting no two runs on a baseline collide;
TestSheetPdfKeepsValuesWhole pins that the fix does not truncate data
that could have been shown. Any new cell drawing must keep both true.
pdfTr(), which
also normalizes /thin spaces to plain spaces (fpdf only wraps
lines at real spaces; contenteditable HTML is full of nbsp and the
lines wrapped comically early before this).pdf/document.go is
a small CSS-shaped layout engine (boxes → pdfBox → pdfItem),
not a stream of fpdf.Write calls. It exists so the export
paginates exactly like the editor's page preview:collapseWS). Pasted markup is hard-wrapped with real newlines;
fpdf's Write treats those as forced breaks, which used to leave
a wide blank gutter down the right of every page and inflate the
page count.SetCellMargin(0) + SetAutoPageBreak(false): the browser wraps
at the content edge, and a block that would cross the bottom
margin moves to the next page whole (place), the same rule
updatePageGuides() uses in docs.js.flow), empty blocks follow the browser's
rules (<p></p> = 0 tall, <p><br></p> = one line, a trailing
<br> adds nothing), and #editor img { height: auto } means the
aspect ratio wins over a height attribute.docs.css (font size, line-height, block
margins, cell padding, list indent) must be mirrored by the
constants at the top of pdf/document.go, or the two page counts drift
apart.ODF (odf/odf.go + od{t,s,p}_{reader,writer}.go):
the zip must store the mimetype entry first and uncompressed
(buildOdfZip does this). XML round-trips through the order-preserving
onode tree. Formula translation =SUM(A1:B2) ⇄
of:=SUM([.A1:.B2]) lives in ods_{writer,reader}.go.
XLSX also round-trips charts as native DrawingML parts
(xlsx/charts.go) and cell notes as
comments (xlsx/notes.go).
cd src
go test ./mod/office/ # converter unit tests (every format)
go test ./wasm/office/ # the WebAssembly bridge's conversion table
go vet ./mod/office/ ./wasm/office/
gofmt -l mod/office/ wasm/office/ # must print nothing
node --check web/Office/docs/docs.js # etc. for each edited JS file
node web/Office/sheets/test_formula.js # formula engine
node web/Office/sheets/test_formula_fns.js # formula functions (vs. Excel examples)
node web/Office/common/test_share.js # share links and OOXML app detection
node web/Office/common/test_pdfcore.js # PDF export: which text lands on which line
node web/Office/slides/test_lines.js # line styles, line ends, callout adjustments
node web/Office/docs/test_pdfimport.js # PDF import: lines, paragraphs, lists, tables
sh ../scripts/check-conventions.sh --diff origin/master
pdf_test.go has pdfStreamsText()
which zlib-inflates PDF content streams so you can assert real text
operators — use it for any new PDF feature.python-docx, python-pptx, odfpy and pymupdf open the
generated files and expose their structure. When PPTX/DOCX behaves
weirdly in a real Office app, generate a reference file with
python-docx/python-pptx and diff the XML part-by-part — that's how
both the pagination and media problems were cracked.fitThumbs() measures the box and sets --sl-thumb-scale; a hard-coded
scale is how the right-hand edge of every preview came to be missing..claude/launch.json has a webroot-static config that serves
src/web/ on :8123; the apps load standalone (AGI calls fail
gracefully). The ribbon, menus and editing are all testable this way;
a phone layout needs a real narrow viewport (the ribbon switches on
window.innerWidth), e.g. headless Chrome with device-metrics emulation.PDF Viewer/js/pdf.js
is already in the tree and will rasterize the bytes into a canvas from a
scratch page served by the same static server. Reading getTextContent()
off each page is the quick regression check: every string that is on the
slide should come back, because anything that fell back to a raster
would not.common/fonts, common/pdfcore.js); the Go renderer behind Sheets
still transliterates, because fpdf's core fonts are cp1252.pptx/chart.go, from the
c:numCache / c:strCache values, so no embedded workbook is needed),
but they are written as the client-rendered PNG in props.png. The
suite's own copy keeps the live chart, so this only shows once
PowerPoint has saved the file (the copy is then stale and the PNG is
what gets imported). xlsx/charts.go already writes DrawingML charts
for Sheets and is the place to start..pptx (p:grpSp, p:timing):
kept in the embedded copy, not written as PowerPoint's own, so they are
lost once PowerPoint saves the file..pptx parts (the
embedded copy keeps them for the suite).props.mask) round-trips through .pptx as the
picture's prstGeom and is a real clip path in the browser-rendered
PDF, but the .odp writer does not draw one — ODF would need a custom
shape with a bitmap fill.dgm:), 3-D effects, shadows and animations are
skipped rather than approximated.sharedspace AGI lib was built for this).Happy hacking. The code tries hard to explain itself — when something looks odd (mimetype-first zips, nbsp scrubbing, sidecar zips), there is a comment at the site explaining why, and usually a test pinning it down.