# Changelog
All notable changes to Kotoba are documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and Kotoba follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.5.0] - 2026-10-20
Attachment captions, and two fixes to rendered HTML.
### Added
- Attachments have a caption: the optional `caption` field of
`Kotoba.Nodes.Attachment` (JSON key `caption`, written only when set)
and of the editor's attachment node. An image's caption is its `alt`
text and its `figcaption`; a PDF's, a video's or another file's is the
text of its download link and the name of its viewer or player. Plain
text and Markdown (``) use it too, and so does the
`:untrusted` policy. With no caption, the file name shows, as before.
`Kotoba.Nodes.Attachment.label/1` returns the caption, else the name.
- The editor has a caption field under the selected attachment: a click
or Alt+F10 goes to it, Enter keeps the caption, Escape leaves it as it
was. Keeping a caption is one undo step, and a shared editor sends it
to the others.
- `Kotoba.Content.from_markdown/2` with `:attachments` makes the alt text
of `` the
attachment's caption, unless it is empty or the file name. A caption
the attachment has already wins.
([#49](https://github.com/hattoriai/kotoba/pull/49))
### Fixed
- A nested list in rendered HTML no longer shows a second marker: the
item that holds it, which has no text of its own, has the
`kotoba-li-nested` class, as in the editor.
([#48](https://github.com/hattoriai/kotoba/pull/48))
- `kotoba.css` sizes a rendered image attachment: its `img` is no wider
than the text and keeps its proportions, with the radius of the
editor's images, and its `figcaption` is small and muted. A large
screenshot rendered at its natural width and overflowed the column.
([#49](https://github.com/hattoriai/kotoba/pull/49))
## [0.4.0] - 2026-10-20
Attachments of files on the server, underline and highlight in Markdown,
one collaboration socket for the shared editors of a page, and stable
collaborator cursors. This release has a breaking change, listed under
Changed.
### Added
- `Kotoba.Attachments.store/2` makes an attachment of a file on the
server, as an upload does: it checks the file, stores it, and deletes it
again when the storage's result makes no valid attachment. For seeds,
imports, and files an app makes itself. `Kotoba.Live.consume_uploads/4`
stores uploads with it.
- The `:attachments` option of `Kotoba.Content.from_markdown/2`: a
paragraph of only `` images becomes the
attachment of that name, or a gallery of several.
### Changed
- Underline and highlight have Markdown: `Kotoba.Renderer.to_markdown/2`
writes `__underline__` and `==highlight==`, and
`Kotoba.Content.from_markdown/2` reads them back. They were dropped
before, so a document turned into Markdown and back (an AI translation,
say) lost them. Text colors and the color of a highlight still have no
Markdown.
([#47](https://github.com/hattoriai/kotoba/pull/47))
- **Breaking:** `__text__` read from Markdown is an underline, not bold.
Kotoba writes bold as `**text**`.
- The warning of an upload's preview that fails names "the file" rather
than "the upload".
- The shared editors of a page share one collaboration socket, each with
its own channel, instead of opening a socket each: a page of 20 shared
editors opens one WebSocket, not 20. A missed revision or removing an
editor affects that editor's channel only, and so does a push timeout
unless a ping finds the connection dead, which reconnects the socket
once for all its editors. A socket takes up to `Kotoba.Collab.token/3`'s
new `:max_channels` editors, 100 by default; pass a lower
`:max_channels_per_transport` of the socket there.
([#38](https://github.com/hattoriai/kotoba/issues/38))
### Fixed
- Collaborator cursors keep their last known position when awareness arrives
before the referenced characters or paragraph, then follow the new position
once the document catches up.
([#44](https://github.com/hattoriai/kotoba/pull/44))
## [0.3.0] - 2026-10-17
Full Markdown. This release has breaking changes, listed under Changed.
### Added
- `Kotoba.Content.from_markdown/2` reads CommonMark and GitHub Flavored
Markdown with MDEx (comrak, a port of GitHub's cmark-gfm): setext
headings, `__` emphasis, nested emphasis, entities and escapes,
reference links, link titles, autolinks, images, `+` bullets and `1)`
lists, nested lists and check lists, lazy lines, `~~~` and indented code,
tables with column alignment, and footnotes. Every example of the GFM
spec (CommonMark included) reads into Kotoba and writes back to Markdown
that renders the same, but for raw HTML, which is text, and list items
that hold blocks (see below); a test runs them all.
- `from_markdown/2` takes `features:`: a construct whose feature is off
becomes its closest form, with no text lost.
- **Pasted Markdown** becomes rich text: plain text that reads as Markdown
(and no rich HTML) goes to the server, which reads it as
`from_markdown/2` does, with the editor's features. `<.kotoba>` renders
the server's half itself (`Kotoba.MarkdownPaste`, a LiveComponent): an
app adds no code. `paste_markdown={false}` turns it off.
- **Quotes that hold blocks**: paragraphs, lists, code, tables and other
quotes, with Lexical's own `shadowRoot` opt-in on the quote node.
- **Images from a URL** (`image` node, the `images` feature): Markdown's
``, in the text. The URL is checked as a link's is,
and the `:untrusted` policy renders the alternative text.
- **Footnotes** (`footnotereference` and `footnotedefinition` nodes, the
`footnotes` feature), numbered in the order of their first reference,
in a list at the end of the rendered HTML.
- **Blank lines**: the empty paragraphs that a person types between
blocks keep their height in HTML (`
`) and are ` ` in
Markdown, which reads back. The `blank_lines: :collapse` render option
and `<.kotoba blank_lines={:collapse}>` leave them out.
- Table columns keep their alignment (`kotoba-align-*` classes, `:-:` in
Markdown).
### Changed
- **Breaking:** MDEx is a dependency: a native library, precompiled for
Linux (glibc 2.35 or later, and musl), macOS, Windows and FreeBSD; on
another system it builds with Rust.
- **Breaking:** the lines of a Markdown paragraph are one line, as
CommonMark has them (a line ending with two spaces or `\` is a line
break). The old reader made each line a line break.
- **Breaking:** a quote read from Markdown is a quote of blocks:
`
...
`.
- **Breaking:** `image`, `footnotereference` and `footnotedefinition` are
built-in node types: an app node cannot have them.
- **Breaking:** `h5` and `h6` render as themselves (they were `h4`).
- The Markdown of `Kotoba.Renderer.to_markdown/2` nests formats (a format
opens once over the text that has it), keeps a URL with spaces or
parentheses in angle brackets, and gives two lists in a row different
markers, so that it reads back as the same document.
- `Kotoba.Features` has `images` and `footnotes`. An editor with a
`features` list has them only when the list names them.
- A list item with several paragraphs, or with a code block, a quote or a
table, reads as an item with line breaks and the blocks after the list:
a Lexical list item holds inline content only.
### Security
- The lock file of the repository has bandit 1.13.1 (for CVE-2026-105659
and CVE-2026-105660) and decimal 3.2.0 (for CVE-2026-97853). The Hex
package does not have the lock file: an app gets these fixes with
`mix deps.update bandit decimal`. Bandit is for the development server
of Kotoba only. Kotoba does not call `Decimal.round/3`.
## [0.2.2] - 2026-10-17
### Changed
- Kotoba supports Phoenix 1.7 and Phoenix LiveView 1.1 (it needed Phoenix
1.8 and LiveView 1.2): it requires `~> 1.7.14 or ~> 1.8` and `~> 1.1`.
Nothing changes for an app on the newer versions. The floor job of CI
runs the tests on Elixir 1.18 with Phoenix 1.7 and LiveView 1.1.
### Fixed
- A colleague's edit in a shared editor no longer takes the focus and the
caret from another editor of the page, so what the author types next is
no longer lost: an editor without focus restores its selection in the
model only.
## [0.2.1] - 2026-10-08
### Fixed
- A text format button (Bold, Italic, Underline, Strikethrough, Inline
code, Subscript, Superscript, Highlight without the palette), in the
toolbar or the selection menu, takes the format off text that has it,
instead of applying it again; at the caret, it turns the format off for
the next text. The color palette at a caret in colored text shows its
colors. ([#36](https://github.com/hattoriai/kotoba/issues/36))
## [0.2.0] - 2026-10-02
### Added
- A selection menu: `<.kotoba selection_menu>` shows a menu over the
selected text, with the default commands (bold, italic, underline,
strikethrough, inline code, highlight, link) or the commands of a list;
`<:selection>` with the new `kotoba_selection_menu/1` gives the app's own
buttons. Alt+F10 focuses it and Escape closes it. It is themed with the
new `--kotoba-floating-*` properties (also in `kotoba-sumi.css`).
- A link card: with the caret in a link, a card shows the URL (it opens in
a new tab) and Edit link and Remove link buttons. Cmd/Ctrl+click opens a
link of the editor.
- `Kotoba.Content.from_markdown/2` reads quotes, check lists, horizontal
rules, pipe tables, `*italic*`, `~~strikethrough~~` and `***both***`,
nested formats (a link in bold), and the first number of a numbered
list: Kotoba's own Markdown now reads back.
- A readable baseline for `<.kotoba_content>` (headings, paragraphs,
lists, quotes, links, code), with the weight of one class so that an
element reset such as `a { color: inherit }` does not undo it, and
`highlightRenderedContent()` to color rendered code blocks with the
editor's grammars.
- Optional collaboration: shared documents with participant cursors,
read-only viewers, per-author undo and redo, local draft recovery after
reconnect or reload, and form submission of an accepted server revision.
See the [Collaboration guide](guides/collaboration.md) for setup and storage.
- PDF and video previews (#6, #7). A PDF shows in the browser's viewer (an
`object` with a download link for a browser that has none), in the
editor and in the rendered HTML. MP4 and WebM videos are checked from
their bytes (`video/mp4`, `video/webm`; QuickTime, Matroska and audio-only
files stay `application/octet-stream`), served inline, and play in a
`video` with controls, `preload="metadata"` and no autoplay; in the
editor, a video that does not load shows as a file. An attachment's new
`preview` (a PDF's first page, a video's poster) comes from the
`:preview` option of `Kotoba.Live.consume_uploads/4`, and must be a safe
URL. `Kotoba.Storage.Local.Plug` answers `Range` requests (`206`,
`416`), which video seeking needs. `Kotoba.Nodes.Attachment.pdf?/1` and
`video?/1` are new.
- Image galleries (#5): a `gallery` node (`Kotoba.Nodes.Gallery`, part of
the `attachments` feature, valid only under the root) that holds
attachments, rendered as a `div.kotoba-gallery` grid. Images uploaded
together make a gallery, each in the place of its own marker (the order
stays when uploads finish in another order); an image uploaded with an
image of a gallery selected joins it. The arrow keys move between the
images and out of the gallery, `Alt+Left` and `Alt+Right` move an
image, Backspace and Delete remove one, and the live region says the
position ("2 of 3: cat.png"). The toolbar's Image group (`gallery`,
`image-previous`, `image-next`) shows while an image is selected: it
groups the image with the images next to it, ungroups a gallery, and
moves an image. A gallery of one image becomes that image.
- Suggestions (#26): text that the server streams into the editor, for
example the answer of a language model. `Kotoba.Live.stream_start/4`
(`at: :selection | :caret | :after | :end`, `format: :markdown | :text`,
`label`), `stream_chunk/4`, `stream_end/3`, `stream_cancel/3` and
`stream_ref/0`. The text shows in a panel as it streams, rendered from
the whole text at each chunk (a Markdown format cut by a chunk is never
half a format), with only the editor's features; Accept
(`Cmd/Ctrl+Enter`) inserts it as one undo step, Reject (Escape) leaves
the document and the selection as they were, and Stop keeps what has
come. The `assist` attribute gives the toolbar an Assist menu of the
app's actions: an action pushes `kotoba:assist` (`ref`, `action`, the
selected text), and the editor pushes `kotoba:suggestion` (`accept`,
`reject`, `stop`). Extensions ask with `context.assist/2`. The dev
server has a fake model, and the Suggestions guide streams Claude with
Req.
- Guides: Editing features (every feature, its toolbar button, keyboard
and Markdown shortcuts, colors, links, code blocks, tables and custom
toolbars) and Rendering (the HTML of each node, styling, HTML/text/
Markdown outside a page, content without the editor). The quickstart
has a complete LiveView, and the README a feature overview.
- Richer prompts (#8). A prompt is a callback, or options: `spaces: true`
(queries with spaces, "Ada Lovelace", ended by two spaces),
`min_length`, `max_length` (up to 200), `items:` (a local list that the
editor filters, with no request), `insert: :text` or
`insert: {:node, type}` (text or a node of the app, from the item's
`:text` and `:attrs`), and `async: true` (the search runs in
`start_async`; `Kotoba.Live.handle_prompt_async/3` pushes its result).
The menu says "Keep typing to search", "Searching…" and "Results did
not load" (a search that failed, with `error: true` in the reply, or
that had no answer after 8 seconds), keeps the answers of its queries,
and drops an answer to an older query. `Kotoba.Prompts.search/3`,
`config/1`, `specs/1`, `find_spec/2` and `filter/2` are new.
- A color palette (#4): the Highlight button opens a palette of text
colors and highlights (red, orange, yellow, green, blue, purple, gray)
and "Remove color", from the mouse and the keyboard. A color is stored
as a name in the text node's `style`
(`color: var(--kotoba-color-red)`), and renders as a class
(`span.kotoba-color-red`, `mark.kotoba-highlight-green`); any other
style is dropped in the editor and never rendered.
`Kotoba.Nodes.Text.colors/1` reads them. The highlight format with no
color stays the default yellow highlight, so existing documents render
as before. A text color is part of the `highlight` feature.
- Underline, highlight, subscript and superscript are features, with
their keyboard shortcuts (`Cmd/Ctrl+U`, `Cmd/Ctrl+Shift+H`,
`Cmd/Ctrl+,`, `Cmd/Ctrl+.`) and toolbar commands. The default toolbar
has Underline and Highlight; an app's toolbar can have Subscript and
Superscript. The `==` Markdown shortcut highlights only in an editor
with `highlight`. Highlighted text has its own colour,
`--kotoba-highlight` (a light yellow), not the selection's.
- Features: `<.kotoba features={~w(bold italic links lists)}>` gives an
editor only those built-in features (`Kotoba.Features`: bold, italic,
underline, strikethrough, highlight, subscript, superscript,
inline_code, links, headings, quotes, lists, check_lists,
code_blocks, horizontal_rules, tables, attachments, mentions). A feature
that is off has no node, toolbar button, Markdown shortcut or keyboard
shortcut; pasted content of it comes in as paragraphs and text, and a
stored node of it is kept as an unknown node. With no list, an editor
has every feature, as before.
- `Kotoba.Content.validate_features/3` refuses, in a changeset, a document
with a feature that the field does not have; `Kotoba.Features.used/1`
and `check/2` read the features of a document.
- Extensions: `<.kotoba extensions={[url]}>` loads JavaScript modules that
add nodes, `register` (commands, transforms, listeners, with a cleanup),
Markdown shortcuts and toolbar controls (`:`, with
`aria-pressed`, visibility and the live region) to an editor. The
built-in features are extensions of the same form. A module that fails
to load or register is logged, and the editor mounts with the rest. See
the Extensions guide, and the example callout extension of the
development server.
- `kotoba_toolbar` takes an extension's command in a `button` slot.
- A code language picker: in a code block, the toolbar has a "Code
language" `