Writer Studio (standalone writing editor) (part 2)
Part 2 of the Writer Studio page: the formatting toolbar, find and replace, the slash menu, document templates, tags, cloning, bulk operations, rename, font and spacing controls, Save as, the editor theme and colour palettes, and the two writer data-model tables.
On this page
What it is
This is part 2 of the Writer Studio (standalone writing editor) page. It covers the editor surface and the document list around it — the formatting toolbar, the find bar, slash menu and template picker, the row-level document operations, the font, spacing, theme and palette controls, Save as, and the two data-model tables behind all of it.
Where to find it
Writer Studio opens from the Writer virtual project in the sidebar, and the parent page covers how the feature is gated, which of its two surfaces you are looking at, and the first-run wizard. Within the writer view the formatting toolbar is one slim row under the document header that hides with one click, the document list occupies the left sidebar, every AI control (writing guidance included) lives under the AI button in the document header, and the theme, palette, Visual effects, toolbar style, default text size and line spacing controls live under the gear icon (Writer settings) beside it.
How it behaves
Formatting toolbar
A Word-style formatting toolbar (FormatToolbar.tsx) is one slim row directly under the
document header, on a desktop and on a phone alike, so it never covers the page. It is hidden in
Focus mode and in book view. With the Icons + labels toolbar style each button also shows its
name. Left to right: Undo · Redo, a paragraph-style dropdown (Normal text / Heading 1–3),
the Font and Text size dropdowns, Bold · Italic · Strikethrough · Code,
Bullet list · Numbered list · Quote, and Link · Divider · Clear formatting. On a desktop
the row ends, at the right, with a Page settings button (three dots) and a hide button
(an up arrow).
Font and Text size (
WriterLookPickers.tsx) set the look of the whole open document, not the selected text, and each document remembers its own — see "Font, text size, page width and line spacing" below.Page settings (
WriterPageShapePickers.tsx, desktop only) opens a small menu with the open document's Page width (Standard, Wide, Full width — listed only in Continuous scroll) and Page layout (Continuous scroll or Paginated), the current choice ticked — see "Page layout: Continuous scroll or Paginated" below. A phone shows neither, because every width fills its screen.Undo / Redo are the leftmost two buttons; they reflect the Tiptap editor history state (
can().undo()/can().redo()) and disable when no action is available. They are keyboard-equivalent to Ctrl+Z / Ctrl+Y.Buttons reflect the cursor's context — a toggle shows
aria-pressed/ the accent style when the selection is inside that mark or block; the dropdown shows the current block's style.Link opens a small inline box to type a URL (auto-prefixed with
https://when no scheme is given; onlyhttp/https/mailtoare accepted), with a Remove option on an existing link.Clear formatting runs
unsetAllMarks()+clearNodes()(matches Word's "Clear All Formatting").
Hiding the toolbar (desktop)
- Hide it — one click on the up arrow at the right end of the bar hides it, and the row takes no space at all.
- Bring it back — the pen button in the document header, just left of the gear
(Writer settings), shows the bar again; click it again to hide it. The pen is lit while the
bar shows, and its tooltip says what a click will do. Alt+B (rebindable, action
toggleWriterFormatToolbar) does the same, and the up arrow's tooltip shows that key. - Remembered on this computer — the hidden state is the
writerFormatToolbarMinimizedsetting, shared by every document and the popped-out Writer window. - Phone: unchanged. The bar stays above the page, and the pen and hide buttons are not shown.
Code: components/FormatBarEnd.tsx (the Page settings button and the hide button, passed into
FormatToolbar as its end slot) and WriterView.tsx, which renders the row right under the
document header while it is not hidden. The older writerFormatToolbarFrame setting, from when the
bar floated and could be dragged, is no longer read.
The toolbar is markdown-clean: every action maps to a command StarterKit already serializes to markdown, so the stored format stays markdown (no HTML). There are deliberately no Underline, text-color, or alignment buttons — markdown has no standard representation for them, and adding them would require embedding HTML in the stored content. Clicking a button, pressing the keyboard shortcut (Ctrl+B…), and typing markdown all drive the same Tiptap commands.
Find & replace
Cmd/Ctrl+F opens an in-document find bar (FindBar) over the editor — query + replace inputs,
case-sensitive and whole-word toggles, an "N of M" count, and next / previous / Replace / Replace-all.
The key is intercepted (preventDefault); Esc closes
and clears the search.
Matching runs in a custom ProseMirror extension (editor/extensions/FindReplace.ts, the
InlineAutocomplete pattern — permitted by I20's Wave-2b clarification): all matches are highlighted via
inline decorations (.writer-find-match; the current one also .writer-find-current), and it edits
PLAIN TEXT only so the document stays markdown-clean (I3). Match ranges come from the pure findAllMatches
(lib/find-matches.ts — exact substring, case / whole-word, non-overlapping) over collectTextBlocks
(the SAME text→position map the chat "apply edit" flow uses). Replace-all runs last match → first so
an earlier match's position never shifts under a later edit.
While a query is live, a keystroke does not rescan the document. The existing match ranges are remapped through the transaction's position mapping instead (a range an edit swallows is dropped), the state is flagged dirty, and the full rescan is debounced ~150 ms behind the last edit — so typing stays responsive in a long document and the "N of M" count settles a moment later.
Slash "/" menu
Type / at a line start (or after whitespace) to open a floating command menu at the caret,
filtered by what you keep typing; up/down move, Enter runs, Esc dismisses. Commands: Heading 1-3,
Bulleted / Numbered list, Quote, Code block, Divider (pure StarterKit chains -> clean markdown, I3/I20), From
template (opens the TemplatePicker), and the AI commands Continue writing (via the existing
aiAutocomplete, stale-guarded), Summarize, Explain, and Improve writing (the last three
open the Assistant + send via sendChat). The AI commands reuse the existing cost-cap + humanized-error
flow; no new bridge.
Detection is a pure matchSlashQuery (lib/slash-trigger.ts) over the text before the caret, wrapped
in the SlashMenu extension (editor/extensions/SlashMenu.ts) that computes { active, query, from }
PURELY in the extension's apply (no dispatch-from-view) and SKIPS code blocks. The command list is
lib/slash-commands.ts; the floating UI + keyboard live in components/SlashMenu.tsx -- the keyboard
is a capture-phase listener mounted ONLY while the menu is open. On pick it deleteRanges exactly the
/query before running the command.
Document templates
Creating a new document (the sidebar + or the empty-state create button) opens a
template picker (TemplatePicker) with a Blank option first,
then any user-defined templates (accent-colored border), then the built-in starter templates
(src/shared/writer/writer-templates.ts).
Picking one seeds structured markdown (and, where it helps, a writing-guidance seed) via the existing
createDocument → setContent → updateGuidance path (the same flow as a Drive import). The picker
ONLY ever seeds a fresh document — there is no "apply to the open document" path, so it can never
overwrite an existing draft, and Blank preserves the one-click create.
User-defined templates
Users can save any open document as a reusable template via the BookmarkPlus button in the
document header. The template captures the document's title, markdown content, and writing guidance
(goal, audience, tone). Templates are stored in the writer_templates table (see "Data model"
below) with soft-delete and are global per install (no account_id).
User templates appear ABOVE the built-in templates in the picker with an accent-colored border.
Each user template has a hover-visible delete button (Trash2 icon) that soft-deletes it. The picker
fetches user templates via writerApi.templateList() on every open.
The IPC handlers support full CRUD:
| Surface | List | Get | Create | Delete |
|---|---|---|---|---|
| IPC | WRITER_TEMPLATE_LIST |
WRITER_TEMPLATE_GET |
WRITER_TEMPLATE_CREATE |
WRITER_TEMPLATE_DELETE |
Template operations do NOT emit writer:documents-changed pushes (templates are a separate entity
from documents).
Document clone
The document row context menu includes a Duplicate action that atomically copies a
document. cloneWriterDocument reads the source row, creates a new document with a
"Copy of [title]" prefix, copies all metadata fields (goal, audience, tone, creativity,
folder), and duplicates the document's tags. The clone is a fully independent document
with its own id and timestamps. Cloning a nonexistent or deleted document returns
undefined (the handler shows a humanized error). The WRITER_DOCUMENTS_CHANGED push
fires after clone so the sidebar refreshes.
Document tags
Documents can be tagged with freeform text labels for organization and filtering.
Tags are stored in a junction table writer_document_tags (created by migration
20260903023357):
| Column | Type | Notes |
|---|---|---|
document_id |
TEXT FK | references writer_documents.id |
tag |
TEXT | the tag label (case-sensitive) |
created_at |
TEXT | ISO timestamp |
Primary key is (document_id, tag). Adding a duplicate tag is a no-op (INSERT OR IGNORE). Tags are loaded alongside documents via loadAllDocumentTags (a single
query that batch-loads all tags grouped by document id, avoiding N+1).
In the document list, each row shows up to 3 tag chips with an overflow count. A tag filter bar appears above the document list when any tags exist; clicking a tag filters the list to documents carrying that tag. The row context menu includes a "Tags" item that opens a tag management popover with an input to add new tags and buttons to remove existing ones.
Templates, tags, copies and export in Writer Studio (native)
Writer Studio has these document tools, over the same tables and channels.
Contract: writer-library-contract.
- Start from a template. New from template in the create menu, or the From template
item in the
/menu, opens a picker: a Blank card, then your saved templates, then the built-in ones, with one search box over all three. Picking one creates the document, saves the template's text, then its writing guidance, and only then opens it. If the text cannot be saved the new document is removed; if only the guidance fails, the document is kept and you are told. A built-in template also records itself on the new document (templateId) and, when it has one, its word goal, in the same meta update as the guidance. A saved template of your own records neither, so its documents show the generic page icon. - Save as template. An item in the document's File menu. It stores the title, text and guidance as a snapshot; later edits do not reach it. An empty document is refused with a plain sentence. The template's name is the title cut to 200 characters. A saved template's delete button is always visible, not hover-only, and asks for confirmation.
- Tags. Each list row shows up to three tag chips, then +N. Manage tags in the row menu opens a small dialog: the tags as removable chips, a box where Enter adds one, and suggestions from every tag in use. Adding or removing a tag does not change the document's last-edited time, so it never reorders the list or makes the next autosave conflict.
- Filter by tag. A row of tag pills appears above the list once any document is tagged. Picking one narrows the whole list, folders included, and works together with a search. Picking it again clears it, and it clears itself if no document carries that tag any more.
- Duplicate. Makes a "Copy of" document with the text, guidance and tags, and opens it. The copy carries none of the original's share page, board card, knowledge-base note, project item or chat links.
- Export from the list. Export as Markdown and Export as HTML in the row menu use the same export as the File menu. A failure is reported in words; cancelling the save dialog is silent.
- Translate. The Language row of the Assistant panel's Fix tab. It opens From (detected) and To language pickers, and the translation is reviewed before it applies like any AI edit (part 3).
The four row actions work on one document at a time; with several selected they show as disabled,
with a tooltip saying why. None of these actions has a keyboard shortcut: the / menu is already
the keyboard path to templates, and the rest are one click away in a menu.
- In the web client (a phone or browser linked to the app) templates, tag editing, Duplicate and
the
/template command all work (since 2026-10-14). Only file export is hidden there, because it saves through a file dialog on the computer. - From the command line, the same actions are routes on the local control server:
POST /writer/documents/:id/clone,POST /writer/documents/:id/tags(body{ tag }),DELETE /writer/documents/:id/tags/:tag,GETandPOST /writer/templates, andDELETE /writer/templates/:id. They use the same saving code as the app, so a document copied or tagged from the command line shows up in the open Writer. Copy and template create accept anX-Client-Request-Idheader, so a retried request never makes a second copy.
Multi-select and bulk operations
Shift-click or Ctrl/Cmd-click selects multiple documents in the list. Shift+Arrow extends the selection. Press Delete or Backspace to bulk-delete the selection (a confirmation dialog names the count). The row context menu on a multi-selection shows a bulk Delete action; other actions gray out with "Only works on one document at a time."
Inline document rename
Double-clicking a document title in the sidebar, or choosing "Rename" from the row
context menu, turns the title into an inline text input. Commit with Enter or blur,
cancel with Escape. The cancelDocRenameRef pattern prevents a blur-after-Escape
from committing the cancelled value (same pattern as folder rename).
Font, text size, page width and line spacing
Each document keeps its own font, text size and page width. The Font and Text size dropdowns in the formatting toolbar, and the Page width choices in its Page settings menu, save to the open document only, so switching documents switches the look with them.
- Font — 13 choices in five groups: Book Serif (the default, an old-style serif stack
led by Iowan Old Style and Palatino Linotype); App font, Arial, Verdana, Trebuchet MS
(sans-serif); Georgia, Times New Roman, Palatino, Garamond (serif); Courier New
(monospace); and Caveat, Dancing Script, Patrick Hand (handwriting). The list is
WRITER_FONTSinsrc/shared/writer-fonts.ts. The three handwriting fonts ship with the app (woff2 under the SIL Open Font Licence, insrc/renderer/src/assets/fonts/, loaded byfeatures/writer/writer-fonts.css), so they look the same on every computer; the others are standard system fonts with fallbacks. - Text size — 12px to 24px in steps of 2. A document that was given an in-between size keeps it, and the dropdown shows it. A bigger size does not widen the page — it fits fewer words on each line of the same page.
- Page width — Standard (about 70 characters per line, the readable default),
Wide (about 100) or Full width (the page fills the writing area, however wide
the window is). Useful on a large monitor, where the Standard page leaves most of the
screen empty. The list and its measures are
WRITER_PAGE_MAX_WIDTHinsrc/shared/writer-page-width.ts. On a narrow window the wider choices simply fill what room there is.
A document with no choice of its own uses the app-wide defaults: Book Serif
for the font, Standard for the page width, and the Font size in the gear menu (in the document
header; writerFontSize in appearance-settings.ts, default 18px) for the size. The gear
menu size reads as "the size for documents that have not picked one".
Line spacing stays app-wide, in the gear menu: Compact (1.4), Normal (1.6) or Relaxed
(1.9, the default), stored as writerLineSpacing.
All four reach the editor as CSS custom properties (--writer-font-family,
--writer-font-size, --writer-line-height, --writer-page-max-width) on the editor
wrapper, built by writerLookStyle in features/writer/lib/writer-look.ts. The first
three are read by .writer-prose .ProseMirror in globals.css; the page width is read
by the page itself (WRITER_PAGE in styles.ts, max-w-[var(--writer-page-max-width,70ch)]).
The size is written in rem (size / 16), so it also follows the app-wide text zoom.
Page layout: Continuous scroll or Paginated
Each document chooses how it is shown while you write. The Page layout choice, in the formatting bar's Page settings menu (the three dots near its right end), has two choices:
- Continuous scroll — one long page that grows as you type. This is how every document has always looked, and what a document that never chose shows.
- Paginated — the document sits on separate US Letter sheets (8.5 × 11 in with 1-inch
margins), like a word processor's page view. When a line no longer fits at the bottom of
a sheet it moves to the top of the next one as you type. A paragraph breaks only between
lines, and a heading moves to the next sheet whole. The sheets follow the Writer theme and
color palette: every sheet carries the same
writer-pagelook as the Continuous scroll page (WRITER_SHEET_CARD: palette colors, accent glow, paper grain), the text is inked from the palette through the stack'swriter-sheet-stackclass, and the cover band sits flush on top of the first sheet with no gap, its icon tile drawn over the sheet's top margin (WRITER_SHEET_HEADERis positioned above the absolutely placed sheet cards; a bottom margin there once left a dark strip across the cover).
While a document is Paginated the Page width choices are hidden from the Page settings menu, because the sheet sets the width; the document's width choice is kept and comes back in Continuous scroll. Alt+Ctrl+L switches the open document between the two (rebindable as Toggle Writer page layout), and the dropdown's tooltip shows the key.
Zoom in Paginated view
While a document is Paginated, the status bar under the page carries a zoom control: a − button, the current percentage, a + button, and Fit page, which sets the zoom so one whole page fits on screen. Each document remembers its own zoom, on a 50%–200% range in 10% steps, and a document that never chose one shows 100%. Alt+Ctrl+= zooms in, Alt+Ctrl+- zooms out and Alt+Ctrl+Shift+0 fits the page, all rebindable in Settings. The app-wide text size keeps Ctrl+= and Ctrl+-, which is why the Writer zoom uses the Alt+Ctrl pair.
Zoom changes only how big the pages look. The sheet stays US Letter, and line breaks, page size and where the pages break stay exactly where they were. Choosing a zoom, like choosing a layout, does not count as editing the document: it does not move its "last modified" time.
Page breaks are only drawn on screen. They are never saved into the text, never appear in a
version, and never become an undo step, so switching back to Continuous scroll leaves the
document exactly as it was. A phone always shows Continuous scroll and hides the choice,
because a full sheet does not fit a phone screen; the document keeps its choice for the
desktop. A copied document keeps its layout and its zoom. Stored per document as page_layout
(scroll / paginated, empty means Continuous scroll) and page_zoom (50–200, empty means
100), settable from the command line through the document's existing meta route
(pageLayout, pageZoom).
Choosing a font, size, page width or page layout does not count as editing: it does not move the document's "last modified" time or its place in the list, and it never changes the text itself.
Font family and size pickers in the toolbar (native Writer)
The native formatting toolbar carries the Font and Text size dropdowns between the
paragraph-style picker and the Bold/Italic buttons (Page width lives in its Page settings menu); each saves to the open document
(above). Font ids come from WRITER_FONT_IDS: the default is book (Book Serif), and system
is labeled App font, the app's own body font, so a custom theme's typeface can still be
chosen for the editor. A stored id the build does not know reads as Book Serif. Neither dropdown
depends on the editor being ready.
The native editor applies them through --writer-font-family and --writer-font-size on its
root (.writer-prose .ProseMirror reads both). The size is written in rem against a 16px
baseline, so the editor still follows the app-wide text size. Headings keep their own rem
sizes, as in the KMS editor.
Collapsing the document sidebar (native Writer)
The panel icon at the end of the document-list header collapses the sidebar, the document list, to a 44px gutter labelled "Documents", so the page can use the
whole width. Clicking anywhere on the gutter brings the sidebar back. The state is the
writerSidebarCollapsed setting (default off) and persists across launches. It is desktop-only:
on a narrow window the list is the whole pane, so the saved flag is ignored there and the
collapse button is not shown. Collapsing never remounts the editor.
Save as (local file export)
The File menu includes a Save as submenu with two options:
- Markdown (.md) — writes the raw markdown content to the chosen path.
- HTML (.html) — converts the markdown to HTML via
markdownToExportHtml(the same converter used for Google Docs export) and writes it.
Both open a system save dialog (dialog.showSaveDialog) with a default filename
derived from the document title (sanitized via sanitizeTitleForPath). Empty
documents cannot be exported (the handler returns a humanized error). The same export
options are also available in the document row context menu in the sidebar.
Editor theme and color palette
The Writer editor can use a different light/dark theme from the rest of the app, and an
optional color palette that restyles the page and the Writer's own chrome. Both live in the
gear menu (Writer settings) in the document header (WriterAppearanceMenu), which holds, top
to bottom: the theme switch, Palette, Visual effects, Toolbar, Font size, Line
spacing, Status bar, then AI model, Autocomplete model and Book view.
- Theme — a three-way switch: Match app (default), Light and Dark. When the
explicit choice differs from the app's current mode, the Writer root gets a
.writer-lightor.writer-darkclass (computeWriterThemeClassinlib/writer-theme.ts) that overrides the--color-surface-*-rgbcustom properties, so everysurface-*utility inside resolves to the other mode. - Palette — a submenu with None plus eight palettes: Parchment, Midnight Ink, Candlelight, Noir, Velvet, Frost, Sage and Rose. Each row shows a small gradient swatch drawn in the current mode. Every palette has a light and a dark version, chosen by the Writer's effective mode (its own theme, or the app's when it matches the app). None draws the page in the app theme's own colors.
- Visual effects — a check item, on by default (
writerVisualEffects). Off, the page keeps its palette colors but loses its glow and paper grain, the cover band is hidden, and no animation plays. The Writer root carries the classwriter-effects-offwhile it is off. - Toolbar — four button styles: Icons + labels (icon and full text, on the formatting toolbar too), Icons only (icon with a tooltip, default), Compact (icon and a shortened label), and All icons (everything icon-only, including the File, Share and Send-to menus, the AI button, Preview and Publish). The AI button always shows its sparkle icon in the theme accent color and the label "AI" in every style except All icons.
The theme switch's two mode buttons render writer.themeMenu.dark and writer.themeMenu.light.
Those are the menu's OWN keys, and they must stay its own: writer.themeDark and
writer.themeLight already hold the older tooltip sentences ("Editor theme: dark (click to
match app)" and its light twin), and i18next resolves a catalog key before the code's inline
default, so pointing the buttons at those keys makes them render a whole sentence instead of a
two-word label, in every language. Nothing catches that by reading the code, because a spec that
stubs t() to return its fallback never sees the catalog; the spec that locks it
(writer-appearance-menu-theme-menu-keys.test.tsx) resolves through the real assembled English
catalog for exactly that reason.
One palette registry
Every palette lives in ONE place: WRITER_PALETTE_DEFS in src/shared/writer/writer-palettes.ts.
Each entry carries its label key and English label, a mood line (the words the cover art
prompt uses), a grain flag (Parchment and Candlelight get a static paper-noise overlay), and a
light and a dark set of tones: page gradient start and end, page border, accent, second
accent, ink, and four chrome surface steps (or null to leave the chrome to the app theme).
Everything that looks at a palette reads that registry:
WRITER_PALETTE_VALUES(re-exported fromappearance-settings.ts) is derived from its keys, so thewriterPalettesetting, the cover-generate request schema and the menu share one list.writerPaletteVars(palette, dark)turns the chosen tones into CSS custom properties, set as an inline style on the Writer root (WriterView.tsx):--writer-page-from-rgb,--writer-page-to-rgb,--writer-page-border-rgb,--writer-accent-rgb,--writer-accent-2-rgb,--writer-ink-rgb, plus--color-surface-50to--color-surface-300and their-rgbtwins when the palette tints the chrome. A palette name the registry does not know reads as None.writerPaletteSwatch(palette, dark)draws the menu swatch.src/renderer/src/features/writer/writer-look.css(loaded by the editor) is the only stylesheet that draws the look, and it reads only those variables. The.writer-pageclass (onWRITER_PAGE, on every Paginated sheet and on every book page) gets the paper gradient, border, ink color, a top highlight in the second accent, an accent glow and the app's lift shadow; headings, links, list markers, quotes, dividers, the selection and the caret take the accent. The grain is added only under.writer-grainand never under.writer-effects-off; effects off also drops the glow. There are no per-palette class names any more.
To add a palette: add one entry to WRITER_PALETTE_DEFS (label key and English label, mood,
grain, and both a light and a dark tone set), and add the translations for its label key.
Nothing else changes: the setting, the menu, the swatch, the page, the cover gradient and the
cover art prompt all read the registry.
Document cards in the list
Each document list row shows a tinted tile with its template's icon, the title, a one-line plain-text preview of the start of the text, a chip with the template's name (built-in templates only), the relative time and the Published icon. Grid cards show the icon tile beside the title, and compact rows show the icon alone. The open document's row has an accent-tinted border. The pin and Actions buttons appear on hover or focus, and always on a touch screen.
The preview comes from the list query: it reads only the first 400 characters of the body,
strips markdown with writerDocumentPreview (src/shared/writer/writer-document-preview.ts)
and cuts the result to 100 characters at a word boundary. It is on list rows only, never on a
single-document read. The icon is writerDocumentIcon(templateId)
(lib/writer-template-icons.ts): a document with no template, or a template id the build does
not know, gets the generic page icon.
Cover band
While Visual effects is on, the top of the open page carries a 120 px cover band with the document's template icon on a tile at its lower edge. It is hidden in book view.
- Every document has its own gradient with no setup:
writerCoverGradient(documentId)(lib/writer-cover-gradient.ts) hashes the document id into an angle and two soft blobs, and paints them in the current palette's variables, so a document keeps its shape while its colors follow the palette. - The Cover options button on the band opens Generate cover art, Upload image and, when the document has an image, Remove cover image. One cover action runs at a time.
- Upload image opens a file dialog for PNG, JPEG or WebP, up to 10 MB. The file is checked by its bytes, not its name, and copied in; canceling the dialog changes nothing.
- Generate cover art runs on your own Gemini API key (Settings > My API Keys), never on Omniscio credits. It first confirms "This makes one picture with your own Gemini API key. Google may charge your account for it." Only after the click on Generate does it send one request straight to Google's Gemini image API for one wide (16:9) picture, from the document title and the palette's mood, with no text in the picture, and record its token use as Writer spend. No Gemini key, a key Google refuses, a used-up Google limit, a picture Google declines, or a timeout each shows a plain sentence and changes nothing.
- An image that fails to load falls back to the gradient.
- The web client (a phone or browser linked to the app) shows the band but not the Cover options button, because choosing and generating covers runs on the computer.
Cover files live in the app's data folder under writer-covers, named
<document id>-<random id>.<png|jpg|webp>; the document stores only that name. The page loads
them through the writer-cover://cover/<name> scheme (never a file path), which serves only a
name of that exact shape and only bytes that are really a PNG, JPEG or WebP. Replacing or
removing a cover deletes the old file, a duplicate never shares its original's cover, the
retention purge deletes the cover of a purged document unless another document still uses it,
and Factory reset wipes the whole folder. Covers are not in backups yet (a known gap listed
in backup-scope-inventory.ts).
Writing sprint
Writing sprint (the timer icon at the right end of the header, or Alt+Ctrl+I) opens a
panel with a timer, an optional word goal and Hold my alerts, then Start. The sprint hides both
Omniscio sidebars and the Omniscio toolbar (a plain strip keeps the window buttons; nothing about
your saved sidebar settings changes), plus the document list, the formatting toolbar, the folder
breadcrumb, the Write / Read switch and every header button. The status bar becomes a quiet
sprint line (time left, words written or goal progress, Alerts held, Esc to leave). Esc,
Alt+Ctrl+I or the lit timer icon ends it, and leaving Writer mid-sprint ends it too. It is desktop only
(the Alt+Ctrl+I shortcut, toggleWriterFocusMode, does nothing on a phone or off the Writer
screen), it is never on at the same time as book view, and it is not remembered across restarts
(focusMode in useWriterBookStore).
Live preview
A template that declares a preview gets a Preview button in the document header, and
Alt+Ctrl+X (toggleWriterPreview) toggles it on the Writer screen. Today that is the
Social media post template, previewed as an X post with a 280-character limit
(X_POST_CHAR_LIMIT).
- On a desktop the preview is a column beside the page (
WriterPreviewPanelHost, which reads the live document text itself so typing does not re-render the whole view); on a phone it is a bottom sheet. Opening the preview closes the Assistant and opening the Assistant closes the preview. It is hidden in book view and closes itself when you open a document whose template has no preview. - It shows a mock post with hashtags in the accent color and any text past the limit highlighted, a ring meter, and "N of 280 characters" with "N over" when it is too long.
- Counting follows X's rules (
lib/x-post-count.ts): the markdown is stripped first (heading, list and quote markers, emphasis, link and image syntax, dividers, and the template's "Hashtags / tags:" label), the text is normalized, then every link counts 23 characters whatever its length, every emoji counts 2, Chinese, Japanese, Korean and other wide characters count 2, and everything else counts 1 per user-perceived character. - Trim to fit is enabled only while the post is over the limit. It asks the AI to shorten the whole post to fit, keeping the hook and hashtags, and the answer goes through the same review as Apply guidance to document: nothing changes until you keep it, change by change, and the version history takes a snapshot first. Like that action it refuses an empty document or one over 6,000 characters.
Hashtags on the page
The editor's Hashtag extension (editor/extensions/Hashtag.ts) draws every #word as a small
accent chip. It is a decoration only, so the saved markdown never changes, and it skips code.
Status bar pieces
The bar under the page shows, in order: the word goal, the word count, the character count,
the read time, and Saved at the far end. Each has its own switch in the gear menu's Status
bar submenu, all on by default (writerShowWordGoal and writerShowSaved join the three
earlier switches).
- Word goal belongs to the document. With no goal it reads Set goal, which opens a small number field (1 to 100,000; Enter saves, Esc cancels, Clear removes the goal). With a goal it shows a progress bar and "N / goal words"; click it to change or clear the goal. A built-in template can preset one (Blog post 800, Essay 1,000, Newsletter 600, Press release 400, Email 200, Social media post 50).
- Saved reads "Saving..." while a save is in flight and "Saved" otherwise. It replaced the old saving pill in the document header.
- A highlighted passage changes the word and character pieces to show both numbers: "6 of 60 words" and "44 of 317 characters". The selected part is counted with the same rules the whole document uses (a hyphenated word is one word, a flag emoji is one character, a link's hidden address is never counted), so a line-by-line count matches the line's own share of the document. Nothing selected puts the whole-document numbers back. The word goal keeps counting the whole document either way.
One-shot moments
src/renderer/src/features/writer/writer-moments.ts plays a short animation once at a moment
that matters, through playWriterMoment(element, kind): rewrite (a light sweep across the
page when an AI edit, an alternative or a whole-document rewrite is applied), publish (the
Publish button pops after a successful publish), goal (the goal bar glows when the word count
crosses the goal), page (the book spread fades up when the page turns) and reveal (the
welcome and empty screens rise in when they first appear). Each adds the class
writer-moment-<kind> (rules in writer-moments.css) and removes it when its animation ends;
calling it again restarts it cleanly. Nothing loops and nothing animates a blur. It plays nothing
when the system or the app asks for reduced motion or Visual effects is off, and the stylesheet
also stops every moment under prefers-reduced-motion, html[data-a11y-reduced-motion='on'] and
.writer-effects-off.
Templates: icon, word goal and preview
Built-in templates are WRITER_TEMPLATES in src/shared/writer/writer-templates.ts. Each one
declares:
icon(required) — one ofWRITER_TEMPLATE_ICON_NAMES. The renderer maps each name to its icon inWRITER_TEMPLATE_ICONS(lib/writer-template-icons.ts), and the build fails if the two lists disagree.wordGoal(optional) — a whole number from 1 to 100,000, given to a new document made from it.preview(optional) —{ type: 'x-post', charLimit }, which turns on the Preview button and panel for its documents.
To add a template: add an entry with an id, its label and description keys and English
defaults, a title, the markdown body, optional guidance, and an icon; add wordGoal or
preview only when they help. If it needs an icon not yet on the list, add the name to
WRITER_TEMPLATE_ICON_NAMES and the icon to WRITER_TEMPLATE_ICONS. Add translations for its
label and description keys (writer-template-catalog-sync.test.ts checks them against the
English catalog). A document's type
chip is simply the template's own label, so it needs no new key.
The pop-out Writer window (WriterWindowApp) renders the same WriterView, so every setting
above works identically in the standalone window.
Content model limitations
The editor is a Tiptap markdown editor — it supports headings, lists, quotes, code blocks, links, dividers, and inline marks (bold, italic, strikethrough, code). It does not support:
- Tables — no table extension is loaded.
- Images or media — no image embedding or media blocks.
- AI image generation — no in-document image generation (cover art sits in the band above the page, never in the text).
- Real-time collaboration — single-user editor, no concurrent editing.
- Voice input or dictation — no speech-to-text integration.
- Copy-paste formatting — pasted content is normalized to plain markdown.
- Checkboxes / task lists — not available in the editor schema.
The writing surface
The writing surface is a portrait sheet — WRITER_PAGE in
src/renderer/src/features/writer/styles.ts caps the line length at the document's page
width (70 characters for Standard, the default) and gives the panel its rounded corners
and generous padding, so it reads like a page rather than a strip. Its writer-page class takes
the palette look from writer-look.css (above). The cover band, when shown, is the page's top
edge (WRITER_PAGE_HEADER, passed to the editor as pageHeader); in Paginated it sits just
above the first sheet (WRITER_SHEET_HEADER, as wide as a sheet), outside the sheet stack so it
never moves a page break. Under the page, the status
strip in WriterEditorHost.tsx shows the pieces described under "Status bar pieces".
There is no "Add page" page break you can insert: the editor's extensions are FindReplace,
InlineAutocomplete, SlashMenu, Hashtag and PageBreaks, and PageBreaks only draws the
display-only spacers of the Paginated layout (above). To see the writing laid out as printed
pages, use book view below.
Closing a document
A X sits beside the document title, and Close document is the first item in the header's File menu. Either one - or Ctrl+W while you are on the Writer screen - closes the open document: the pending save is flushed first, book view, outline and cards and focus mode close, and the screen returns to the empty Writer screen with your document list. Nothing is deleted, and reopening it from the list is one click. A closed document stays closed until you open one, so the screen does not quietly reopen a different document for you.
Ctrl+W is only the close key on the Writer screen with a document open. Everywhere else it keeps its Omniscio meaning, Archive session, and it can never reach that action while a Writer document is on screen. Close document is an ordinary rebindable action - Settings, Keybindings, "Close Writer document" - and the condition that scopes it is the writerDocumentOpen shortcut fact, which holds only while the Writer screen is showing and a document is open (never on its Sessions tab). The archive action keeps Ctrl+W and E untouched; the shortcut engine tries the scoped action first and falls through to the archive action everywhere the document is not on screen.
Book view and typesetting
A Write / Read switch sits beside the document title (Outline and Cards sit between the two when chapters are on; Alt+Ctrl+Shift+Q flips read view; Focus is described above). Read view, called book view in code and settings, shows the open document as printed book pages: Two pages shows facing pages like an open book (page 1 alone on the right), Four pages shows four pages in a two-by-two grid, and a phone shows one page at a time (swipe or use the arrows). The arrow and Page Up / Page Down keys turn pages while the pages have focus. Clicking a page goes back to writing with the cursor at the first paragraph of that page.
The Typesetting button opens the print settings for that one document: page size (5 × 8, 5.25 × 8, 5.5 × 8.5, 6 × 9, A5, US Letter), margins (Narrow, Normal, Wide, with a wider inside margin), font (the Writer font list; the document's own font by default), size (9–14 point), alignment, line spacing, where a chapter begins (each Heading 1, or each Heading 2), whether chapters start on the next page or on a right-hand page (a blank page is added when needed), and page numbers. Chapter openings drop the title down the page and set the opening words in small capitals. Reset to defaults puts the document back to 6 × 9 in, Normal margins, 11 point.
Book view only shows: it never edits or re-saves the text, and the pages wear the same page look as the editor (the app theme, or the Writer's own theme and palette). The Book view check item in the gear menu turns the whole feature off. A print-ready PDF that matches the pages is not part of this release; today's PDF export uses its own fixed layout.
For agents: the layout is the nullable writer_documents.book_layout column (JSON), validated by
writerBookLayoutSchema in src/shared/writer-book-layout.ts, and travels as one more look key
on the ordinary meta update — bookLayout on writer:update-meta and on
PATCH /writer/documents/:id, read back on GET /writer/documents/:id. Send a full layout object
or null to reset; a look-only patch never moves updated_at.
Related
The surfaces that frame these controls — the document-list view modes, search, folders, version history and autosave — are on the Writer Studio (standalone writing editor) page. The AI capabilities that read this document and its guidance are in part 3, sharing and integrations in part 4, and the IPC reference in part 5.
Every Writer shortcut, and changing them (desktop)
Writer shortcuts fire only on the Writer screen. Where one wanted the same keys as an Omniscio shortcut, a system-wide hotkey, the one-handed layout preset or an operating-system key, the WRITER side moved: Omniscio's own bindings never do, because a system-wide hotkey is taken by the operating system before the Writer window ever sees it, and a matching in-app binding would run the other feature instead.
| What it does | Default keys |
|---|---|
| New document | Alt+N |
| Fold or show the document list | Alt+L |
| Comment on the highlight (or show the comments) | Alt+M |
| Hide or show the formatting bar | Alt+B |
| Outline view | Alt+Ctrl+H |
| Cards view | Alt+C |
| Read (book) view | Alt+Ctrl+Shift+Q |
| Continuous or paginated pages | Alt+Ctrl+L |
| Writing sprint | Alt+Ctrl+I |
| Live preview | Alt+Ctrl+X |
| Research with sources | Alt+R |
| Check the writer's voice | Alt+I |
| Project notes | Alt+D |
| Lock or unlock the passage | Alt+U |
| SPaG Check panel | Alt+Ctrl+Shift+Z |
| Floating dictionary | Alt+Ctrl+Shift+Y |
| Floating story names | Alt+Ctrl+Shift+J |
| Ask for a critique | Alt+Ctrl+C |
| Ask me questions | Alt+Ctrl+Y |
| Outline and stop | Alt+Ctrl+8 |
| Blurb | Alt+Ctrl+9 |
| Next or previous spelling issue | F8 / Shift+F8 |
| Show the spelling suggestions | Ctrl+. |
| Use suggestion 1, 2 or 3 (number row or number pad) | Ctrl+Shift+1, 2, 3 |
| Accept the top suggestion | Alt+Shift+Enter |
| Ignore once on the suggestions card | I |
| Add to the dictionary / story word list | Alt+Ctrl+A / Alt+Ctrl+Shift+V |
| Ignore once / everywhere | Alt+Ctrl+E / Alt+Ctrl+Shift+E |
| Hide or show spelling marks | Alt+Ctrl+Q |
| SPaG panel: keep, skip, keep all | Alt+Enter, Alt+X, Alt+K |
They all work wherever the cursor is on the Writer screen, not only inside the document, and each one is rebindable: Writer settings (the gear at the right of the document header) -> Keyboard shortcuts. A key another shortcut already uses, a key Omniscio holds as a system-wide hotkey, and a key the operating system keeps for itself are each refused with a sentence saying why.
Last verified 2026-10-19