ORIX Docs
ORIX Docs — Write Without Limits.
ORIX Docs is a native macOS word processor with real pagination, styles, tables, equations, citations, track changes and document comparison. It works entirely on the Mac: no account, no telemetry and no network code, with DOCX and PDF as first-class exchange formats.
| Metric badge | Exact value in the source | Source file |
|---|---|---|
| Engine tests | 582 tests, 85 suites, 10 targets, result passed, 0 issues |
docs/reports/test-results.json |
| Interaction scenarios | 19 scenarios, 19 passed, 0 failed | docs/reports/test-results.json, docs/reports/selftest-release.json |
| Engine line coverage | 92.9 % (26198 of 28196 lines; application target not included) | docs/reports/coverage.json |
| Version, minimum macOS | 1.0.0 (build 2), minimumSystemVersion 15.0 |
dist/release.json (not committed; copied into docs/release/distribution.md), project.yml |
| Notarization | application and disk image both Accepted |
dist/release.json, copied into docs/release/notarization.md |
| DMG size | 30810813 bytes | dist/release.json, copied into docs/release/distribution.md |
| DOCX round trip | 19 documents; text integrity after two cycles 100.00 % (word-weighted, 526 words) | docs/reports/docx-compatibility.md |
| PDF export · 487 pages | pdf_export_ms 1395.518458 |
docs/reports/benchmarks.json |
| Open + first layout · 487 pages | open_and_first_layout_ms 452.972959 |
docs/reports/benchmarks.json |
| Keystroke relayout · 487 pages | keystroke_relayout_ms.median 14.027374999999999 |
docs/reports/benchmarks.json |
There is no continuous-integration service and therefore no "build passing" badge; the test badges quote the last recorded local run. Badge rendering on the SPB Git website has not been checked (see Release Status).
The main window in Writing mode on the Research Report template: outline, paginated canvas with ruler, Typography inspector, status bar with page, word and character counts.
Highlights
- A real page. A Core Text typesetter and an in-house paginator: sections, columns, headers and footers, footnotes, widow and orphan control, keep rules, tables that split by rows with repeated headers.
- Structure first. Paragraph and character styles with inheritance, six themes, numbered headings, an outline that can move whole sections.
- Academic tooling. LaTeX equations, captions, cross-references, a per-document reference library (BibTeX, RIS, CSL-JSON) and six built-in citation styles.
- Review. Track changes with per-change accept and reject, comments with replies, and a document comparison that produces a merged document of tracked changes.
- Honest exchange. DOCX import and export with a warning for everything approximated or dropped; vector PDF with outline, links and structure tags; Markdown, HTML, RTF and plain text.
- Private by construction. No account, no telemetry, no network code. On-device writing assistance only where the system provides it, always as a proposal to accept or reject.
Table of Contents
- Overview
- ORIX Philosophy
- Application Preview
- Editing Engine
- Page Layout
- Typography
- Styles
- Tables
- Images and Objects
- Mathematics
- Academic Writing
- Long Documents
- Track Changes
- Document Comparison
- DOCX Compatibility
- PDF Publishing
- Native Format
- Autosave
- Templates
- Publishing Studio
- Local AI
- Research Assistant
- Document Auditor
- Automation
- Architecture
- Technology Stack
- Installation
- Build Instructions
- Testing
- Benchmarks
- Privacy
- Accessibility
- Localization
- Roadmap
- Release Status
- Known Limitations
- ORIX Ecosystem
- License
Overview
ORIX Docs 1.0.0 is a document-based macOS application (ai.spboucher.orix.docs) for macOS 15.0 or later. It is a thin SwiftUI + AppKit shell over ORIXDocsKit, a Swift package of eleven engine targets that do not import SwiftUI and can be built, tested and benchmarked from the command line (architecture overview).
| Native document | .orixdoc — a single ZIP file with a SHA-256 manifest (persistence) |
| Opens | .orixdoc, DOCX, RTF, Markdown, HTML, plain text, PDF (text only) |
| Exports | .orixdoc, DOCX, PDF, RTF, Markdown, HTML, plain text |
| Interface languages | English, Canadian French |
| Workspace modes | Writing, Page Layout, Review, Academic, Publishing, Focus |
| Command line | orixdocs (convert, audit, stats, compare, workflow), bundled in the application |
| Network use | None |
What this README states is backed by a file in the repository; where something was not done or not verified, it says so. The consolidated list is in Known Limitations.
ORIX Philosophy
ORIX applications share three commitments, described in the brand guidelines and the design system:
- The document belongs to its author. Files stay on the Mac, in a documented open container. Foreign files open as untitled copies; the original is never written (persistence).
- Nothing is lost silently. Every importer and exporter reports what it approximated or dropped as a warning, and the export sheet shows those warnings before the file is written.
- Calm, native tools. One accent pair (ink indigo
#4F46E5, page amber#F59E0B), fixed tokens for colour, spacing and type, and modes that change which panels are shown — never the document.
The competitive position, including where established products remain ahead, is set out in the competitive analysis.
Application Preview
![]() |
![]() |
| Template chooser. Sixteen templates in six categories; each thumbnail is the first page of the template as laid out by the engine. The document language is chosen here. | Writing mode. The Book manuscript template with a drop cap and a centred chapter title; the inspector is hidden. |
![]() |
![]() |
| Light appearance. The Newsletter template, Pages sidebar and Styles inspector. | Dark appearance. The same window. The chrome follows the system appearance; the page stays white, as it will print, and so do the theme and style preview cards. |
Focus mode. Bars, sidebar, ruler, inspector and status bar are hidden and the paragraphs other than the caret's are dimmed; Escape or the close button returns to Writing.
All screenshots in this document are PNG captures of the application's own windows, rendered by AppKit through the launch options driven by Scripts/screenshots.sh; nothing is composited or retouched.
Editing Engine
The editor is not an NSTextView. It is a value-type document model (DocModel), an editing engine that transforms it (DocumentEditor) and a custom NSView (EditorCanvasView) that implements NSTextInputClient (text engine).
- Value-type model. Undo is a stack of document values; snapshots share storage with their successors. Typing is coalesced into one undo step per burst.
- Unicode-safe addressing. Every offset is a UTF-16 offset aligned on a composed-character boundary; a ZWJ emoji is deleted as one character (self-test scenario 2).
- Input. Keyboard movement and selection by character, word, line, paragraph and document; input-method composition (marked text); mouse selection with double and triple click; copy, cut and paste with native, RTF, HTML and plain-text flavours; drops of images, PDF files and text.
- Typing aids. Smart quotes (guillemets with no-break spaces in French) and em dashes; spelling through
NSSpellCheckerwith guesses, Ignore and Learn. - Find and replace in its own panel, honouring change tracking.
Not provided by the custom view: grammar checking, autocorrection, text replacement, Writing Tools, Look Up, dragging text, the system find bar, and a split caret for bidirectional text (limits).
Page Layout
Page Layout mode. The Thesis template at 70 %: thumbnails with their page numbers, and the Document inspector for the current section (paper, orientation, margins, columns, header and footer distances).
DocLayout typesets paragraphs with Core Text and flows them into pages with its own paginator (layout engine, pagination).
- Sections with their own paper size, orientation, margins, columns and page-number format; next-page, odd/even and continuous section breaks; page and column breaks.
- Headers and footers with first-page and odd/even variants, page number, page count and running-heading fields.
- Footnotes at the foot of the column of their reference; endnotes after the body.
- Widow and orphan control, keep lines together, keep with next, page break before.
- Floating images and shapes with square, top-and-bottom, behind-text and in-front wrapping.
- Page backgrounds, borders and watermarks.
- Screen and print paginate identically (
screenAndPrintLayoutsPaginateIdentically).
Limits worth knowing: rows do not split across pages, footnotes do not split, columns are not balanced, and line breaking is first-fit (pagination limits, layout limits).
Typography
Typography inspector. Character and paragraph settings for the selection in the Academic paper template; the page shows footnotes, a three-rule table and a numbered display equation.
Character formatting covers font family, weight (100–900), size, bold, italic, underline, strikethrough, superscript and subscript, small caps and all caps, text colour, highlight, tracking, baseline shift, kerning, ligatures and a language tag per run. Paragraph formatting covers alignment, indents, spacing, line spacing (multiple, exact, at least), tab stops with leaders, hyphenation, drop caps, shading, borders and right-to-left direction (CharProps and ParaProps in DocModel/Properties.swift).
Small capitals and bold depend on what the font offers; only italic is synthesised. Hyphenation uses one language per paragraph (layout limits).
Styles
Styles inspector. The Technical manual template: the style at the selection (marked "Modified" when direct formatting differs), the six themes, numbered headings and the paragraph style list.
Formatting is resolved as document defaults → paragraph style chain (basedOn) → character style chain → direct properties. Built-in style identifiers equal Word's (Normal, Heading1, Title, Caption…), which keeps semantics through a DOCX round trip (overview). A style can be updated from the selection or created from it; six themes (ORIX, Classic, Modern, Academic, Editorial, Technical) re-derive the built-in styles.
Tables
Table inspector. The Financial report template with a cell selection: five table styles, header row, row and column commands, merge and split, column width, sorting.
- Insert, delete, merge and split; horizontal spans and Word-style vertical merges; column resizing by dragging.
- Table styles (Grid, Banded, Lined, Academic, Plain), header rows repeated on continuation pages, cell shading and vertical alignment.
- Sorting of body rows and cell formulas with recalculation.
- Captions with sequence fields and a generated list of tables.
Cells hold paragraphs only (no nested tables); a row never splits across pages; table structure changes are not tracked (text engine limits, pagination limits).
Images and Objects
Images are stored once per document and referenced by identifier. PNG, JPEG, GIF, TIFF, HEIC and PDF assets are drawn; a PDF asset is drawn as vector content (its first page). Images can be inline or floating, cropped and rotated, and carry alternative text. Shapes are rectangle, rounded rectangle, ellipse, line, arrow and callout, with a one-line label (layout engine: the page renderer, DOCX: images, shapes, drawings).
Not available: charts, SmartArt, grouped shapes, text boxes as objects, picture effects. Inline objects are unbreakable boxes: one wider than the line overflows it (layout limits).
Mathematics
Equation sheet. LaTeX source with a live preview typeset by the same renderer as the page, inline or display, and a symbol palette.
Equations are LaTeX math typeset by SwiftMath as vector glyphs in the page's own drawing context, on screen and in PDF. Display equations can be numbered and cross-referenced. On DOCX export and import, LaTeX is converted to and from OMML; HTML export can carry MathML (layout engine: equations, DOCX: equations).
This is a subset of LaTeX math mode, not a TeX engine: user macros, align, \underbrace, \overset, \boxed and \tag are among the constructs the library does not support (technology evaluation, section 6). An expression that does not parse is shown as its source in red rather than vanishing, and expressions outside safe bounds are refused before they reach the library (security).
Academic Writing
![]() |
![]() |
| Academic mode. The References inspector: citation style, the document's reference library, and commands for citations, bibliography, captions, lists of figures and tables, and cross-references. | Insert Citation. Works are chosen from the document's library; locator, prefix and suffix are set per work. |
- Reference library per document; import and export of BibTeX / BibLaTeX, RIS and CSL-JSON, with duplicate detection on key, DOI, and title plus year.
- Six built-in citation styles: APA 7, Chicago 17 author-date, MLA 9, IEEE, a generic numeric style and Vancouver. Citations and the bibliography are computed, never stored as text.
- Captions, cross-references, footnotes and endnotes, numbered headings, generated contents and lists of figures and tables.
This is not a CSL processor: a .csl file cannot be loaded, titles are printed as stored, and there are no note-based styles. The deviations from each published guide are listed and tested in the references engine document.
Long Documents
The outline sidebar lists headings with their numbers and moves a heading with everything under it; the Pages sidebar shows lazy, debounced thumbnails; contents, lists of figures and tables, page cross-references and running heads are recomputed by a multi-pass layout that stops when page references are stable (at most four passes) (pagination: generated blocks and convergence).
Measured on a generated 487-page document (177162 words, 80 tables, 320 footnotes, 80 equations): a cold layout in 436.577292 ms and a median relayout after a keystroke of 14.027374999999999 ms — see Benchmarks for the meaning of each figure. Every edit re-flows the body from the first block; what keeps this fast is the paragraph cache, not incremental pagination. No unlimited page count is promised.
Track Changes
![]() |
![]() |
| Review mode. Changes listed by author and kind with per-change accept and reject, comments with replies, and the auditor noting that tracked changes are pending. | Markup on the page. An insertion underlined in its author's colour, a comment tint, and change bars in the margin. Insertions are underlined and deletions struck through, so markup does not rely on colour alone. |
Tracked: inserted and deleted text, paragraph marks, character formatting, pasted content and replacements. Each change records its author and date; a burst of typing is one change. Accept and reject work per change, per selection of changes, or for all (text engine: accepting and rejecting changes).
Not tracked: table structure, inserted or deleted breaks and other atomic blocks, paragraph formatting, styles and lists, link and character-style changes, object resizing and section moves (what is not tracked).
Document Comparison
Comparison window. Two Markdown files compared: a change list, aligned original and revised columns with word-level insertions and deletions, a moved paragraph, a changed table cell, and a button that opens the merged document as tracked changes.
DocReview aligns blocks with a patience and Myers diff, pairs modified paragraphs by similarity, detects moved paragraphs, diffs words inside pairs, and reports formatting, style and structure changes separately from content. The result is a side-by-side view, a report (Markdown or a formatted document), and a merged document in which every difference is a tracked change (document comparison).
Tested invariant, including 40 seeded random edit scripts: accepting every change gives the revised text, rejecting every change gives the original text. Differences the model cannot track (paragraph style, table properties, page setup) are reported but cannot be rejected (limits of the invariant).
DOCX Compatibility
ORIX Docs reads and writes WordprocessingML with its own engine (DOCX architecture, feature-by-feature table). Perfect Word compatibility is not claimed, and Microsoft Word itself was not used in any test; the files were checked with pandoc 3.9.0.2, macOS textutil and LibreOffice 26.8.2.2.
Measured results on the reference corpus, from docs/reports/docx-compatibility.md (generated 2026-11-21T06:47:05Z):
| Measure | Result |
|---|---|
| Documents | 19 |
| Imported without error | 19 / 19 |
| Model equal after the first cycle / the second cycle | 19 / 19, 19 / 19 |
| Words in the corpus | 526 |
| Text integrity after two cycles (word-weighted) | 100.00 % |
| Feature checks passed / failed (feature × document) | 172 / 0 |
| Import warnings: info / approximated / dropped | 11 / 8 / 26 |
| pandoc reads our export | 19 / 19 (mean in-order word agreement 97.9 %) |
textutil reads our export |
19 / 19 (mean word agreement 96.4 %) |
| LibreOffice converts our export to PDF | 19 / 19 |
How to read this:
- The corpus is small and mostly synthetic (pandoc and LibreOffice output, hand-authored OOXML, one ORIX-generated document). It measures the engine on listed features, not on arbitrary real-world documents.
- "Model equal" proves that ORIX Docs reads back what it writes. It does not prove that another application renders the file the same way. Layout (line breaks, pagination, fonts) is not measured anywhere.
- Unsupported content is disclosed, not hidden: charts, SmartArt, embedded objects, linked pictures, macros, tracked moves, nested tables and text boxes are dropped or approximated with a named warning, shown when the file opens and before an export is written.
- Macros, OLE and ActiveX parts are never executed and never preserved; external targets are never fetched (security).
A DOCX file opens as an untitled document: saving creates an .orixdoc, and writing a DOCX is an explicit export.
PDF Publishing
Export sheet. Seven formats; for PDF, bookmarks from headings, structure tags, crop marks and a page range. The lower panel states what this format changes before the file is written.
A PDF is the paginated layout drawn by the same renderer that paints the screen, into a Core Graphics PDF context: vector text with embedded fonts, vector equations, images at their source resolution, external and internal links, named destinations, document metadata, an outline from the headings, structure tags, optional crop marks and a page range (PDF publishing). Pending tracked changes are published as accepted on a copy; comments are not exported.
No conformance to PDF/A or PDF/UA is claimed. No validator was run, no output intent or XMP metadata is written, and the tag structure is partial: tables carry no row or cell structure, lists are flat, headers and footers are untagged, and no document language is written (what is not claimed, known limits). There is no colour management and no CMYK conversion.
Native Format
.orixdoc is one ZIP archive: a mimetype entry stored first, a manifest.json listing every other entry with its size and SHA-256, document.json (the model, sorted keys), assets/ and preserved/ (uninterpreted parts of an imported DOCX) (persistence).
- Strict reading: sizes and checksums are verified before the document is decoded; a newer container or schema version is refused rather than guessed.
- Recovery: a damaged file is read as far as its intact entries allow and opens with a warning; recovery never invents a document.
- Deterministic writing for a given document, generator and creation date, which makes files diffable.
- Schema migrations run on a JSON tree on every read; only schema version 1 exists today.
The format has no encryption and no digital signature: the SHA-256 manifest detects corruption, not tampering. The whole file is rewritten on each save.
Autosave
The application is a classic NSDocument application: autosave in place, versions (Browse All Versions), Revert, Duplicate, Rename and Move To come from AppKit. The autosave delay is 5 seconds. Saving encodes a value snapshot of the model on a background thread, so later edits cannot corrupt a write in progress (autosave, versions and recovery).
Recorded check: "recovery": "PASS: autosaved text survived SIGKILL" in docs/reports/test-results.json — text typed into a saved document was on disk after the process was killed with kill -9 (what the test does and does not prove). Not covered by a test: never-saved untitled documents, a kill in the middle of a write, power loss.
Templates
Sixteen templates in six categories, each a real document with its own style sheet (DocTemplates): Blank; Business letter, Proposal, Financial report, Meeting minutes, Project report, Invoice; Academic paper, Research report, Thesis; Legal memorandum; Résumé, Cover letter; Technical manual, Book manuscript, Newsletter. Templates exist in English and French, chosen in the template chooser. Every template is laid out and published to PDF by TemplateRenderingTests.everyTemplateLaysOutAndPublishes.
Publishing Studio
Publishing mode. The Technical manual template: page thumbnails, a generated table of contents with leaders, and the Publish inspector with document properties, four typography presets and page elements.
Publishing mode gathers what prepares a document for output: document properties, four typography presets (Book, Report, Manuscript double-spaced, Compact) that change the theme, the Body style and the margins in one undoable step, and one-click contents, lists, bibliography and breaks. Export goes through the export sheet.
Local AI
Intelligence inspector. A rewrite proposed by the on-device model for the selected paragraph, shown as changes with Accept, Reject, Insert Below, Copy and Regenerate; the rule-based tools are listed below it.
Writing assistance uses Apple's Foundation Models framework with the on-device SystemLanguageModel only.
| Requirements | macOS 26 or later, on a Mac and in a region where Apple Intelligence is available and enabled. On macOS 15 the feature is unavailable and says why. |
| Actions | Summarise, rewrite, improve clarity, adjust tone (formal, friendly, concise, academic), suggest headings, outline, action items, explain, suggest structure |
| Behaviour | Every result is a proposal with Accept / Reject; nothing is applied silently; one Undo restores the original text |
| Long texts | Processed part by part or by map-reduce within the model's context window; detail is lost on the way and the panel says which strategy ran |
| Guarantee | The server-backed model type of the same framework must not appear in the sources: OnDeviceOnlyTests.noServerBackedModelTypeInTheSources scans App/Sources and the package sources for it |
| Verified on | The build machine (Apple M5 Max, macOS 27.0): model reported available, context size 8192 tokens (technology evaluation, section 9) |
Limits, stated plainly:
- Quality is not measured. No evaluation of the model's output was done and nothing is claimed about it. Output changes with operating-system updates.
- The "concise" tone action often returns the text unchanged; the panel then reports that the model proposed no edit.
- Latency as recorded by the engineer: 1.7–8.5 s per action on a selection of about 235 tokens, measured while the machine was under load — indicative only. These figures are not stored in a report file in the repository; the opt-in test
OnDeviceModelTests(ORIX_AI_TESTS=1) reproduces the measurement. - The model may decline a request; the text is then left untouched.
Research Assistant
The research tools are rule-based and quote the document; nothing is generated (auditor and research assistant). They work without the language model:
- search across body, tables, notes, headers and footers, with whole-word, case, diacritic and regular-expression options;
- undefined acronyms, repeated wording, unreferenced figures and tables, cited passages, action items;
- readability, language identification per paragraph and related-paragraph search on the NaturalLanguage framework (
App/Sources/Intelligence/TextTools.swift).
Repeated-wording and related-paragraph results depend on the language models installed with macOS (limits).
Document Auditor
Document auditor. The Thesis template audited with the Academic profile: findings by severity, each with evidence from the document, its page and a Show button.
DocAudit runs deterministic checks and returns findings with evidence quoted from the document: heading hierarchy, empty and duplicate headings, broken cross-references, missing captions and alternative text, inconsistent formatting, unresolved comments, pending tracked changes, missing or orphaned bibliography entries, unusual page breaks, overflowing tables, missing page numbers, long sentences, double spaces and missing metadata. Four profiles (standard, academic, business, minimal); findings and the report exist in English and French (checks and thresholds).
Automation
Workflows sheet. Four built-in workflows; the steps of the selected one in plain language; input, output folder and overwrite policy.
Three surfaces on one engine (automation):
| Surface | Status |
|---|---|
| Workflows — JSON sequences of document operations, on one document or a batch, with history | Implemented and tested |
orixdocs — convert, audit, stats, compare, workflow run, formats; bundled at ORIX Docs.app/Contents/Helpers/orixdocs |
Implemented and tested |
| Shortcuts actions — Convert Document, Export as PDF, Audit Document, Document Statistics | Compiled; never run from the Shortcuts app |
| AppleScript | Deferred; no scripting dictionary is shipped |
orixdocs convert report.docx report.pdf --theme Academic --paper a4
orixdocs audit thesis.orixdoc --profile academic --json > findings.json
orixdocs compare v1.docx v2.docx --report changes.md --merged merged.orixdoc
orixdocs workflow run docx-to-styled-pdf inbox/*.docx --out published --jobs 4Workflows cannot run scripts or reach the network: the step vocabulary is closed, unknown step types are rejected at load time, and output paths are confined to the chosen folder (security).
Architecture
The diagrams below are Mermaid. Mermaid blocks are emitted as diagrams by the SPB Git website (checked after publication; not reviewed visually by a person); the same structures are explained in prose in docs/architecture/.
1. Modules
flowchart TD
App["ORIX Docs app: SwiftUI + AppKit"] --> Automation[DocAutomation]
CLI["orixdocs command-line tool"] --> Automation
Automation --> DOCX[DocDOCX]
Automation --> Formats[DocFormats]
Automation --> Layout[DocLayout]
Automation --> References[DocReferences]
Automation --> Review[DocReview]
Automation --> Audit[DocAudit]
Automation --> Templates[DocTemplates]
DOCX --> Container[DocContainer]
Formats --> Container
Layout --> Math[DocMath]
Math --> SwiftMath["SwiftMath (third party)"]
Container --> Model[DocModel]
Math --> Model
References --> Model
Review --> Model
Audit --> Model
Templates --> Model
Details: architecture overview.
2. Text editing
sequenceDiagram
participant W as NSWindow
participant C as EditorCanvasView
participant S as DocumentSession
participant E as DocumentEditor
participant P as Paginator
W->>C: keyDown
C->>C: input context, insertText or doCommand
C->>S: perform
S->>E: editing operation
S->>S: register undo unless coalesced
S->>S: store model for background saving
S->>P: layout with cache and previous layout
P-->>S: DocumentLayout
S->>C: layoutChanged
C->>C: redraw visible pages and overlays
Details: text engine, section 8.
3. Layout pipeline
flowchart LR
M[DocumentModel] --> N[Numbering]
M --> PG[Paginator]
N --> PG
PG --> LC[LayoutCache]
LC -->|miss| PL[ParagraphLayout]
PL --> FC[FontCache]
PL --> MR[MathRenderer]
PG --> DL[DocumentLayout]
DL --> PR[PageRenderer]
DL --> GQ["Geometry queries"]
PR --> SC[Screen]
PR --> BM["Thumbnails and previews"]
PR --> PDF["PDF context"]
Details: layout engine.
4. Pagination (simplified)
flowchart TD
A["Start a pass with page references from the previous pass"] --> B["Take the next block"]
B --> C{"Fits in the column with its footnotes?"}
C -->|yes| D["Place lines, apply widow, orphan and keep rules"]
C -->|no| E["Close the column, place its footnotes, go to the next column or page"]
E --> D
D --> F{"More blocks?"}
F -->|yes| B
F -->|no| G["Place endnotes, headers and footers"]
G --> H{"Page references stable, or fourth pass?"}
H -->|no| A
H -->|yes| I[DocumentLayout]
Details: pagination.
5. DOCX import and export
flowchart LR
F[".docx file"] --> Z["ZipReader with limits"]
Z --> X["XML parts: no DOCTYPE, size and depth limits"]
X --> I["Importer: styles, numbering, body, notes, comments, sections"]
I --> M[DocumentModel]
I --> W1["Warnings: approximated or dropped"]
I --> PP["Preserved parts (allow-list)"]
M --> EX["Exporter: body, notes, comments, styles, settings"]
PP --> EX
EX --> W2["Preflight warnings"]
EX --> ZW["ZipWriter, fixed timestamps"]
ZW --> O[".docx file"]
Details: DOCX engine.
6. PDF publishing
flowchart LR
M[DocumentModel] --> C["Copy with pending changes accepted"]
C --> L["Print layout: no markup, no comments"]
L --> R[PageRenderer]
R --> CTX["Core Graphics PDF context"]
R --> H["Render hooks: links and structure tags"]
H --> CTX
L --> O["Outline and named destinations"]
O --> CTX
CTX --> P["PDF data"]
Details: PDF publishing.
7. Citation management
flowchart LR
B["BibTeX, RIS, CSL-JSON files"] --> IMP[BibliographyImporter]
IMP --> MG["Merge: key, DOI, title and year"]
MG --> LIB["Document bibliography"]
LIB --> ENG[CitationEngine]
CIT["Citation inlines in the text"] --> ENG
ST["Citation style setting"] --> ENG
ENG --> T["In-text citation text"]
ENG --> BL["Generated bibliography paragraphs"]
T --> LAY[Layout]
BL --> LAY
Details: references engine.
8. Local AI proposal
flowchart TD
S["Selection and action"] --> A{"On-device model available?"}
A -->|no| U["Explain why; rule-based tools remain"]
A -->|yes| R[IntelligenceRunner]
R --> F{"Fits the context window?"}
F -->|yes| D["One request"]
F -->|no| P["Part by part or map-reduce"]
D --> O[Proposal]
P --> O
O --> V["Shown as changes, with unsupported passages flagged"]
V -->|Accept| AP["One undoable edit"]
V -->|Reject| X["Document untouched"]
Details: Packages/ORIXDocsKit/Sources/DocAutomation/Intelligence/, technology evaluation, section 9.
9. Document persistence
flowchart TD
OP["Open a file"] --> T{"Native .orixdoc?"}
T -->|yes| RD["Strict read: manifest, sizes, SHA-256"]
RD -->|fails| RC["Recover intact entries, warn"]
RD -->|ok| DOC["Document window"]
RC --> DOC
T -->|no| IM["Import: DOCX, RTF, Markdown, HTML, text, PDF text"]
IM --> UN["Untitled copy; original never written"]
UN --> DOC
DOC --> ED[Edit]
ED --> MS["ModelStore: latest value snapshot"]
MS --> AS["Autosave in place, 5 s delay, background thread"]
AS --> FILE[".orixdoc on disk, versions by AppKit"]
Details: persistence.
10. Review engine
flowchart LR
subgraph Tracking
E["Edit with tracking on"] --> RV["Runs carry insertion, deletion or format revisions"]
RV --> AR["Accept or reject: per change or all"]
end
subgraph Comparison
O[Original] --> AL["Block alignment: patience and Myers diff"]
R[Revised] --> AL
AL --> PM["Pair modified blocks, detect moves"]
PM --> TD["Word-level diff and formatting comparison"]
TD --> MD["Merged document of tracked changes"]
TD --> RP["Report and side-by-side view"]
end
MD --> AR
Details: text engine, sections 5–6, document comparison.
Technology Stack
| Area | Choice | Why (see the technology evaluation) |
|---|---|---|
| Language | Swift 6 language mode, strict concurrency complete |
Value-type, Sendable model |
| Interface | SwiftUI panels and sheets, AppKit document architecture and canvas | NSDocument gives autosave, versions and file coordination |
| Text | Core Text typesetting, own paginator, custom NSTextInputClient view |
TextKit 2 cannot flow text through pages with exact geometry |
| Core Graphics PDF context; PDFKit for printing and PDF text import | One renderer for screen and print | |
| ZIP, DOCX, Markdown, HTML | Written in this repository | No suitable Swift library; hostile-input rules under our control |
| RTF | AppKit's RTF codec, plus own picture handling | Local, no WebKit |
| Math | SwiftMath, pinned by revision | Vector glyphs in the page's context |
| Citations | Own formatter for six styles | No maintained Swift CSL processor |
| Spelling, language analysis | NSSpellChecker, NaturalLanguage |
System services, on device |
| On-device AI | Foundation Models, SystemLanguageModel only |
No server-backed model |
| Project | XcodeGen (project.yml), Swift Package Manager |
Reproducible project file |
| Build environment | Xcode 27.2, macOS 27.0, Apple M5 Max | As recorded in the technology evaluation, section 0 |
The only third-party dependency is SwiftMath. Automatic updates (Sparkle) were evaluated and are not implemented in 1.0.0.
Installation
Requirements: macOS 15.0 or later. The application is a universal binary (arm64 + x86_64). It was developed and tested on Apple silicon only: the Intel slice is built but untested.
Download from the SPB Git release v1.0.0: ORIX-Docs-1.0.0.dmg · ORIX-Docs-1.0.0.zip · SHA256SUMS.txt.
| File | Size | SHA-256 |
|---|---|---|
ORIX-Docs-1.0.0.dmg |
30810813 bytes | 94144d313c91a029c44f2dc34add72f84a67dc35881875bcd36615aed5e7e38e |
ORIX-Docs-1.0.0.zip |
29762912 bytes | 1957d5e30931068ae1926ba69d58639e2a975b5aae4183e7f3ca004a9df9d75e |
Disk image. Open ORIX-Docs-1.0.0.dmg and drag ORIX Docs to the Applications folder.
ZIP. Double-click ORIX-Docs-1.0.0.zip and move ORIX Docs.app to Applications.
Verify before opening:
shasum -a 256 ORIX-Docs-1.0.0.dmg ORIX-Docs-1.0.0.zip
# compare with the values above, then:
spctl --assess --type execute --verbose=2 "/Applications/ORIX Docs.app"
# expected: accepted, source=Notarized Developer IDBoth files are signed with a Developer ID, notarized by Apple and stapled, so Gatekeeper can verify them offline. The command-line tool is inside the bundle: "/Applications/ORIX Docs.app/Contents/Helpers/orixdocs" --help. Details: distribution.
Build Instructions
From docs/development/setup.md. Requirements: Xcode with the macOS SDK, XcodeGen; network access once to fetch SwiftMath.
# Generate the Xcode project (after any change to project.yml or to the file list)
xcodegen generate
# Build the app (Debug into build/DerivedData)
Scripts/build.sh # or: Scripts/build.sh release
# Build and test the engines without Xcode
cd Packages/ORIXDocsKit
swift build
swift test --no-parallel
# Run every automated check and write docs/reports/test-results.json
Scripts/test.sh # or: Scripts/test.sh engines | app
# Release: build, sign with the Developer ID in the keychain, embed the tool, verify
Scripts/release.sh
# Notarize with an existing notarytool keychain profile, staple, build the DMG and ZIP,
# check with Gatekeeper, write checksums and dist/release.json
Scripts/notarize.shScripts/release.sh and Scripts/notarize.sh need the maintainer's Developer ID identity and notarization profile; they never create, print or change credentials (signing, notarization). Other scripts: Scripts/coverage.sh, Scripts/docx-compat.sh, Scripts/screenshots.sh, Scripts/recovery-test.sh, Scripts/icons.sh, Scripts/l10n.py.
Testing
Last recorded run, from docs/reports/test-results.json (2026-11-21T03:13:10-05:00):
| Check | Result | What it is |
|---|---|---|
| Engine tests | 582 tests in 85 suites across 10 targets: passed, 0 issues | Swift Testing, swift test --no-parallel, no window |
| Interaction self-test | 19 scenarios: 19 passed, 0 failed | Real NSEvent key and mouse events sent to the document window inside the app |
| The same 19 scenarios, release record | 19 passed, 0 failed (2026-11-21T08:17:06Z) | docs/reports/selftest-release.json, recorded for the Release build |
| Recovery | PASS: autosaved text survived SIGKILL |
Three launches of the built app around a kill -9 |
| XCUITest suite | Not run | macOS Automation Mode needs the owner's authentication, which was not given |
Engine line coverage, from docs/reports/coverage.json: 92.9 % (26198 of 28196 lines), a lower bound of the union across test bundles; command-line tools excluded; the application target is not included.
| Target | Lines | Coverage | Target | Lines | Coverage |
|---|---|---|---|---|---|
| DocAudit | 1669 | 98.4 % | DocLayout | 2479 | 86.2 % |
| DocAutomation | 1667 | 84.9 % | DocMath | 152 | 100.0 % |
| DocContainer | 327 | 100.0 % | DocModel | 3492 | 88.2 % |
| DocDOCX | 5331 | 92.2 % | DocReferences | 3204 | 93.0 % |
| DocFormats | 6297 | 97.2 % | DocReview | 1936 | 92.3 % |
| DocTemplates | 1642 | 99.8 % |
Things to know when reading these numbers (testing):
- Tests that depend on an external tool (Poppler, pandoc, LibreOffice) return early when it is missing, and a skipped check still counts as a passed test. The report records totals, not which optional checks ran.
- The self-test synthesises events inside the process. It does not prove that the window server delivers events and does not exercise an input method, dictation, VoiceOver or drag and drop from another application.
- The tests run serially because laying out documents from many threads at once can stall in the system font registry.
- There are no unit tests in the app target.
Benchmarks
Copied from docs/reports/benchmarks.json and docs/reports/benchmarks-100-pages.json. Machine: Apple M5 Max, 18 active cores, macOS "Version 27.0 (Build 26A5425a)". Build: release. Tool: swift run -c release orixbench on a generated report-like document (headings, body text, footnotes, 9 × 5 tables, display equations, contents, running headers). Times are milliseconds of wall-clock time for one run.
| Key | 487 pages | 98 pages | Exact meaning |
|---|---|---|---|
document.words |
177162 | 35434 | Words in the generated document |
document.blocks |
1884 | 380 | Body blocks |
document.tables / footnotes / equations |
80 / 320 / 80 | 16 / 64 / 16 | |
layout_cold_ms |
436.577292 | 99.381666999999993 | One full layout with an empty cache, all passes included |
layout_passes |
2 | 2 | Pagination passes that layout needed |
keystroke_model_edit_ms.median |
0.12929099999999999 | 0.021208999999999999 | Inserting one character in the model, 200 iterations |
keystroke_model_edit_ms.p95 |
0.24675 | 0.029791999999999999 | |
keystroke_relayout_ms.median |
14.027374999999999 | 2.287166 | The full layout that follows each insertion, warm cache |
keystroke_relayout_ms.p95 |
18.708082999999998 | 2.509417 | |
keystroke_relayout_ms.max |
22.288083 | 2.690083 | |
paragraph_break_at_start_relayout_ms |
13.884333 | 2.2699159999999998 | A paragraph break near the start plus the layout that follows |
find_all_ms (find_matches) |
19.820166 (6480) | 3.7605 (1296) | Find all occurrences of one word |
numbering_ms |
1.024208 | 0.15745799999999999 | One numbering pass |
pdf_export_ms |
1395.518458 | 263.617459 | PDF export with outline and tags, including its own print layout |
pdf_bytes |
3699661 | 880902 | |
native_save_ms |
51.645083999999997 | 10.323708999999999 | Encoding the .orixdoc container in memory; no disk write |
native_bytes |
137483 | 30314 | Size of that container |
native_open_ms |
59.917875000000002 | 11.628083999999999 | Reading and verifying that container from memory |
open_and_first_layout_ms |
452.972959 | 86.408459000000008 | native_open_ms plus a cold layout, timed separately and added |
docx_export_ms |
454.57129099999997 | 88.359542000000005 | DOCX export, including a print layout for page references |
docx_bytes |
42605 | 15815 | Size of the exported DOCX |
docx_import_ms |
116.222583 | 21.128291999999998 | Importing that DOCX |
peak_memory_mb |
338 | 88.5625 | Peak resident size of the whole benchmark process |
Reading these figures (performance):
- They are single runs of a synthetic document on one machine. They show orders of magnitude and how costs scale between two sizes; they are not guarantees for other documents or hardware, and no unlimited page count is promised.
keystroke_relayout_msis the layout cost of a keystroke. It does not include drawing, undo registration or statistics; end-to-end typing latency in the app is not measured.- Not measured at all: drawing a page, scrolling, application launch, memory per document.
- Layout runs on the main thread, and every edit re-flows the whole body; incremental pagination and background layout are not implemented.
Privacy
- No account. Nothing to sign in to.
- No telemetry, no analytics, no crash reporting of its own.
- No network code. By construction, the application and the engines contain no networking calls: the sources contain no
URLSession,URLRequest, Network framework, CFNetwork or WebKit use. Two tests enforce parts of this on every run —OnDeviceOnlyTests.noNetworkCodeInAutomationOrIntelligencescans the automation, intelligence and inspector sources for networking, process-spawning and scripting APIs, andOnDeviceOnlyTests.noServerBackedModelTypeInTheSourcesscans all application and package sources for the server-backed model type (Tests/DocAutomationTests/IntelligenceTests.swift). The application requests no entitlements. - Documents stay on the Mac. There is no sync, no sharing service and no real-time collaboration, by design.
- The only way out is yours. A ⌘-click on an
http,httpsormailtolink hands that URL to the default browser or mail application; no other scheme is opened. - System services. Spelling, language analysis and the on-device model are macOS services. macOS itself may download language assets for them; ORIX Docs does not initiate network requests.
Imported documents are treated as untrusted. Protections, each described with its tests in docs/security.md:
- ZIP limits on entry count, entry size, total size and compression ratio; ZIP64, encryption, duplicate and unsafe entry names refused;
- XML parts with a
<!DOCTYPEor<!ENTITYrefused; external entities never resolved; size, depth and element limits; - macros, OLE and ActiveX never executed and never preserved; external relationships kept as text and never fetched;
- HTML and Markdown parsed by own tokenisers: no script execution, no remote fetches, images only from the source file's folder;
- LaTeX guarded before typesetting and fuzzed;
- SHA-256 integrity manifest in the native container;
- hardened runtime with no exception entitlements.
The application is not sandboxed: a flaw in a parser would run with the user's file permissions (residual risks).
Accessibility
What exists, established by a review of the code, not by a test with assistive-technology users (accessibility review):
- The canvas is an accessibility text area exposing the text being edited, the selection, the insertion point, string and frame for a range, and it posts value and selection notifications.
- Controls carry accessibility labels, state as traits or values, and stable identifiers; decorative images are hidden.
- Every editor command is reachable from the main menu; 45 have a keyboard shortcut.
- Review markup uses underline, strikethrough and change bars, not colour alone.
- Images and shapes carry alternative text; the auditor reports images without it; tagged PDF figures carry it.
- Primary and secondary text tokens meet WCAG AA contrast on every surface in both appearances; tertiary text does not (contrast table).
Gaps: VoiceOver was not tested with a human listener; the canvas exposes flat text without headings, links, tables or tracked changes as structure; Reduce Motion and Increase Contrast are not specifically handled; chrome text sizes are fixed. This is a review, not a certification.
Localization
French interface. Review mode in Canadian French with the French Research Report template: translated modes, sidebar, inspector and status bar, and comma decimal separators.
The interface is available in English and Canadian French (CFBundleLocalizations: [en, fr-CA]). The string catalogue App/Resources/Localizable.xcstrings holds 1469 keys, all with a French translation; Scripts/l10n.py build fails when a key has none. Templates, auditor findings, generated headings ("Notes de fin") and smart quotes follow the document language.
Known imperfection visible in the screenshot above: built-in style names such as "Body" are document data and are not translated. The French translation was not reviewed by a second person. Citation styles localise connecting terms only (references limitations).
Roadmap
An honest list of what is not done, not a promise of dates:
- Run the XCUITest suite once Automation Mode is authorised.
- Validate exported DOCX files in Microsoft Word, Pages and Google Docs, on real-world documents.
- Run a PDF/A and PDF/UA validator; complete the tag structure (table rows and cells, lists, artifacts, document language).
- Run the Shortcuts actions from the Shortcuts app; make intent launches skip the template chooser.
- Test on an Intel Mac and on a clean second Mac.
- A VoiceOver session with a listener; structured accessibility for headings, tables and tracked changes; Reduce Motion and Increase Contrast.
- Automatic updates (Sparkle was evaluated; not implemented in 1.0.0).
- AppleScript: a minimal dictionary with an export command.
- Grammar checking and autocorrection.
- Incremental pagination and background layout; row splitting across pages; column balancing.
- A CSL processor behind the existing
CitationFormattingseam; note-based citation styles. - A wider LaTeX subset (
align,\underbrace,\overset…), dependent on the math library. - App Sandbox for the application, with the command-line tool left unsandboxed.
- Correct the French track-changes label and translate built-in style names.
- Publish the repository and the
v1.0.0release on SPB Git, once authorised.
Release Status
Version 1.0.0 (build 2), recorded on 2026-11-21. Sources: dist/release.json (not committed; reproduced in docs/release/).
| Step | Status | Evidence |
|---|---|---|
| Built (Release, universal: x86_64 + arm64, minimum macOS 15.0) | ✓ | dist/release.json; Scripts/release.sh |
| Signed: Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, no entitlements | ✓ | signing |
Notarized — application: submission 5cbffb9c-d031-4702-81c6-ecb0d1068eca, Accepted |
✓ | notarization |
Notarized — disk image: submission 794c8ee7-f0ef-491f-b7cc-7ab911771eca, Accepted |
✓ | notarization |
| Stapled (application and disk image) | ✓ | notarization |
Gatekeeper: accepted, source=Notarized Developer ID (application and disk image) |
✓ | dist/release.json |
| Checksums (SHA-256) | ✓ | Listed under Installation |
| Public repository on SPB Git | ✓ | https://git.spboucher.ai/orix-docs, published 2026-11-21 with the owner's authorization |
| Tested on a clean second Mac | ✗ | Not done |
SPB Git release v1.0.0 with assets |
✓ | https://git.spboucher.ai/orix-docs/releases: DMG, ZIP, SHA256SUMS.txt, release notes; downloads re-verified (checksums match, DMG stapled, Gatekeeper accepts) |
Published state:
- The repository is public at https://git.spboucher.ai/orix-docs and the release assets are served from
https://git.spboucher.ai/releases/orix-docs/v1.0.0/(DMG, ZIP, checksums). The files were downloaded back from the forge and verified withshasum -a 256 -c,stapler validateandspctl. - The rendering of this README on the SPB Git website was checked after publication: the page is served, every image path resolves and the ten Mermaid diagrams are emitted as diagram blocks. Their visual appearance in a browser was not reviewed by a person.
Full gate-by-gate table: release checklist.
Known Limitations
The consolidated list, grouped by area with a link to the detailed document for each line, is in docs/compatibility/limitations.md. The ones that matter most before relying on ORIX Docs:
Verification gaps
- The XCUITest suite was not run; an in-app interaction self-test driving real
NSEvents was used instead. The two overlap but are not equivalent. - Microsoft Word was never used to validate DOCX files; pandoc,
textutiland LibreOffice were. - No PDF/A or PDF/UA conformance is claimed; no validator was run.
- The Shortcuts actions were compiled but never run from Shortcuts.
- VoiceOver was not tested with a human listener; the accessibility statement is a review by code inspection.
- Intel is built but untested; no clean second Mac was used.
Not implemented in 1.0.0
- AppleScript support (deferred).
- Automatic updates (Sparkle evaluated, not implemented).
- Grammar checking and autocorrection.
- Real-time collaboration — intentionally absent.
- Specific handling of Reduce Motion and Increase Contrast.
- App Sandbox.
Behaviour to know
- Layout from many threads at once can stall in the system font registry: tests run serially and batch jobs bound their concurrency.
- The on-device model's "concise tone" action often returns the text unchanged, reported as no edit proposed.
- Table rows and footnotes do not split across pages; columns are not balanced (pagination limits).
- Track changes does not cover table structure, paragraph formatting or styles (text engine).
- Six built-in citation styles, not a CSL processor (references).
- Equations are a subset of LaTeX math (technology evaluation, section 6).
- Other formats lose what they cannot carry — see the table in format compatibility.
ORIX Ecosystem
ORIX Docs is the macOS member of a family of applications that share the ORIX plate, ring and accent-pair identity (brand guidelines). Its siblings, for iOS and iPadOS, are on SPB Git:
| Application | Platform | Repository |
|---|---|---|
| ORIX Scan | iOS / iPadOS | https://git.spboucher.ai/orix-scan |
| ORIX Calc | iOS / iPadOS | https://git.spboucher.ai/orix-calc |
| ORIX Audio | iOS / iPadOS | https://git.spboucher.ai/orix-audio |
License
© 2026 Simon-Pierre Boucher. All rights reserved.
Third-party notices
- SwiftMath — https://github.com/mgriebling/SwiftMath, pinned at revision
0b0222e102ba415b352cd29f334075622bd4e6aa. MIT License, Copyright (c) 2023 Computer Inspirations. - Math fonts bundled with SwiftMath (
mathFonts.bundle, shipped inside the application's resources): distributed under the GUST Font License and the SIL Open Font License; both licence texts are in the bundle (GUST-FONT-LICENSE.txt,OFL.txt). SwiftMath's README names the licence for Latin Modern Math, TeX Gyre Termes Math (GUST), XITS Math and KpMath (OFL); the bundle does not document the licence of each of the other fonts individually, a point the technology evaluation records as not verified.
Contact: contact@spboucher.ai







