Skip to content

v0.20.0

Choose a tag to compare

@PROVE1352 PROVE1352 released this 12 Nov 07:07
· 167 commits to main since this release

Reload open tabs after the upgrade. A tab that still runs 0.19 or older cannot show columns, and its editor
would delete a group of columns with everything inside it. 0.20 lets such a tab read pages with columns but not
edit them, until it is reloaded (below and docs/adr/2425-*).

A minor release with columns, charts on public links and better find_context answers for Korean questions. Blocks can sit side by side in
two to four columns (/2단, /3단); agents, Markdown downloads, zip export and vault sync carry them as comment
markers. A tab of an older release can no longer delete them: each client tells the server which document schema it
knows, and the server takes edits only from clients that know every node on the page. find_context counts the
shorter form of a long Korean word in titles and headings, prefers sections with the question's rarest word and
gives title words their real weight. A public link can now show the page's charts, drawn as charts from labels and
numbers, once an owner or admin turns it on for that link; public pages also draw callouts (icon, then text) and
text and background colours as the editor does. One database migration, additive: 0061_share_include_charts (three
columns on pages; a 0.19 database goes from 61 to 62 applied migrations, and every existing link keeps charts off).
No new dependency, two optional settings (EMBEDDING_QUERY_PREFIX, EMBEDDING_PASSAGE_PREFIX). The MCP tool list keeps its 48 tools
(32 in core) and their descriptions; every tool now carries its annotation hints (+468 tokens full, +324 core). Upgrade matrix adds v0.19.0 and v0.19.1.

Checked in Chrome only (desktop and a 390 px window): the columns check (31 steps), a 0.19.1 build against the 0.20
server (10 steps), public charts (27 steps), public callouts and colours (16 steps) and the 0.19 browser checks passed; none of it was tried in Safari, Firefox or on a touch device
(docs/KNOWN-ISSUES.md, "Added in 0.20.0").

Upgrade notes

  • Tabs left open over the upgrade (docs/adr/2425-*). Pages without columns: nothing changes, a 0.19 tab edits
    them as before. Pages with columns: a 0.19 tab gets a read-only connection. It shows the page without the group,
    under its lock line ("Locked · … You can read and comment, but not edit": 0.19 reads a read-only connection as a
    lock), next to its own "A new version is available. Reload" notice; typing does nothing and nothing it does
    reaches the page. When someone adds columns to a page a 0.19 tab has open, that tab turns read-only the same way
    within a moment; what it sent in that moment is dropped. After Reload the tab runs 0.20 and edits normally. A 0.19
    tab with offline copies on (the installed app) keeps its editor's deletion of the group as an unsent edit; 0.20
    keeps that edit as a recovery item ("Made by an older version of the app") instead of sending it. A row template
    body with columns refuses saves from a 0.19 tab (409 SCHEMA_OUTDATED).
  • Proxies: the collaboration socket URL now carries a query string (/collab?schema=2). Path rules such as
    Caddy's or nginx's location /collab need nothing; a rule that compares the whole request URI must allow it. A
    proxy that strips the query makes every 0.20 tab look like 0.19: read-only on pages with columns.
  • Migration 0061 (the only one) adds pages.share_include_charts (boolean, default false), pages.share_charts_by
    (uuid, references users, on delete set null) and pages.share_chart_sources (jsonb, the approved chart sources).
    Additive; every existing link keeps its behaviour (charts off) until a manager turns them on in the share dialog.
    Chart numbers on public pages can be up to 10 minutes old (the public render cache); the switch and the person's
    membership apply at once.
  • No re-index: the new find_context rules work at query time. Answers to Korean questions can be ordered
    differently from 0.19; answers cached in memory are dropped by the restart.
  • Going back to 0.19.1 should need no database restore: 0.19 does not read the three new columns (0061 stays
    applied); starting 0.19.1 on a database with 0061 was not tried. But
    0.19 does not know columns and has no guard: its editor deletes a group with its content as soon as someone opens
    the page; do not go back once columns are in use. A page whose link showed charts, published again while 0.19
    runs, keeps the chart setting on for its new link once 0.20 runs again (KNOWN-ISSUES SHARE-9). Not checked beyond
    that.
  • Semantic search: EMBEDDING_QUERY_PREFIX and EMBEDDING_PASSAGE_PREFIX are empty by default, so nothing
    changes. Setting, changing or removing one re-embeds every section at EMBEDDING_REQUESTS_PER_MINUTE; until that
    finishes, sections without a new vector are found by their words only (docs/OPERATIONS.md).
  • API: GET /api/pages/:id/sync-check?schema=N (new query) answers needs when N is below the server's document
    schema; PATCH /api/collection-row-templates/:id takes schema (409 SCHEMA_OUTDATED); page bodies with columns
    carry <!-- inkling:columns --> marker lines in every Markdown format; PATCH /api/pages/:id/share takes
    includeCharts and approveChartSources, ShareStatusDTO and PublicPageDTO gain chart fields (docs/API.md,
    "v0.20.0 additions").

Added

  • Columns (docs/adr/2420-* .. 2424-*). Put blocks side by side: /2단 or /3단 in the slash menu (English "2
    columns", "3 columns"; /columns and /단 find them too) turns an empty line into a group of empty columns with
    the caret in the first one (on a line with text the group goes below it). Any ordinary block goes in a column:
    text, headings, lists, to-dos, images, code, callouts, toggles, tables, embeds. Drag the boundary between two
    columns to change their widths (each keeps at least 15%), double-click it to make them equal. The block menu (⋮⋮)
    of a block in a column adds Add column (up to four), Delete this column (its blocks move to the column on
    its left) and Unwrap columns (everything back as ordinary blocks, in order). Nothing tidies a group on its
    own: an empty column stays until you delete it; Backspace in a group whose columns are all empty removes it.
    Below 640 px of width (phones, a side peek) the columns stack in order. Public links, presentation mode, PDF and
    print, page embeds and the offline copy show the columns, and the image viewer opens on images inside them;
    agents, Markdown downloads, zip export/import and vault sync write them as <!-- inkling:columns --> /
    <!-- inkling:column --> / <!-- /inkling:columns --> lines. A heading inside a column is not a section.
    Written against @blocknote/core's public API; BlockNote's GPL multi-column package is not used. No new
    dependency.
  • Charts on public links (docs/adr/2440-* .. 2444-*). A public link can now show the page's charts: the share
    dialog says "N charts on this page do not show on the public link" and offers Show charts on the public page
    (owners and admins; off by default, per link, audited). When it is on, each chart's labels and numbers are
    published — worked out with the access of the person who turned it on, while they are a member of the workspace,
    and only for the databases and queries the charts used when it was turned on (a chart added later over another
    database waits: "N newly added charts are not public yet", Publish these charts too) — never the rows behind
    them, the database's or view's name, or any id or query text. Public pages draw charts with the app's own chart
    component (also in presentation mode, print and "Save as PDF"; scaled to the paper), with the table underneath for
    screen readers, readers without scripts and the Markdown download. A chart inside a column stands in that column
    (its title and table too). The chart code loads only on pages that have a chart. Without the switch, a folder
    link's charts of its own databases are now drawn as charts instead of tables; everything else is as before.
  • Document schema version (docs/adr/2425-*). Every client says on its collaboration socket which document
    schema it knows (0.20 = 2; none = 0.19 and older = 1). On a page that holds a node type the client does not
    know, its connection is read-only, from the start or from the moment such a node arrives, so an older editor
    never deletes what it cannot show. 0.20 shows "This page has content that only a newer version of the app can
    edit. Reload to update." when that happens to it in a later release.
  • Role prefixes for embedding models: EMBEDDING_QUERY_PREFIX and EMBEDDING_PASSAGE_PREFIX (optional, empty
    by default) for models that expect them, such as the e5 family ("query: ", "passage: "). Changing either one
    re-embeds every section, as a model change does (docs/adr/2404-*).
  • Developers: a recall evaluation set for find_context (32 questions written the way people remember pages, over
    three workspaces) with page@1, page@3 and page MRR in apps/server/scripts/context-bench.ts and
    context-tune.ts (docs/adr/2400-*).
  • Korean guides: deploy/DEPLOY.ko.md, docs/OPERATIONS.ko.md, docs/BACKUP.ko.md, docs/MCP.ko.md,
    docs/QUERY.ko.md, docs/TEMPLATES.ko.md, docs/ARCHITECTURE.ko.md, docs/WEBHOOKS.ko.md, docs/VAULT-SYNC.ko.md,
    docs/PLUGINS.ko.md, docs/API.ko.md, docs/KNOWN-ISSUES.ko.md, docs/PERFORMANCE.ko.md and docs/ROADMAP.ko.md,
    with the same sections, anchors and code blocks as the English files. The Korean README and user guide link to them;
    each English file links to its Korean one.

Changed

  • find_context finds pages people describe with a longer word than the page uses (docs/adr/2401-* .. 2403-*):
    a Korean query word of three or more syllables also counts, with a discount, when its shorter form (the word
    without the last syllable, e.g. 택배함 → 택배, 회의록 → 회의) is in a page title or heading. Sections that miss the
    question's clearly rarest word rank a little lower (×0.75), and words that appear only in titles now carry their
    real weight instead of the "unknown word" minimum. Query time only: no migration, no re-index. On the new recall
    evaluation (32 questions over three workspaces): tuning (dev) questions page@3 0.875 → 1.000 (own workspaces) and
    0.813 → 0.938 (with a 5,000-page workspace); held-out (test) questions page@3 unchanged at 0.938 in both, page@1
    0.750 → 0.813 and page MRR 0.844 → 0.885 with the large workspace, unchanged on own workspaces. Existing questions
    unchanged or better except one test question that loses its second relevant section; latency unchanged.
  • patch_section on a section that holds columns keeps the group: sent back unchanged it stays as it is (same
    block ids), with any change inside it is replaced whole (the blocks in it get new ids); it is never merged with
    an ordinary block. update_page replace of a page with columns keeps the blocks around the group instead of
    rewriting the page (docs/adr/2424-*).
  • find_context's section text writes columns with read_page's marker lines, without indenting the blocks
    inside, so a section copied from find_context into patch_section keeps its group (docs/adr/2424-*).
  • Every MCP tool states all four annotation hints (readOnlyHint, destructiveHint, idempotentHint,
    openWorldHint) from one table, so clients no longer fall back to the spec's defaults ("may be destructive",
    "open world") for tools that only add (docs/adr/2460-*). Before, 21 of 48 tools were marked read-only and 11 had a
    destructive hint. Now 20 are read-only; of the writes, 11 are destructive (including more_tools, which can run
    any hidden tool) and 18 only add or flip a flag; none is open world. Two verdicts changed: catch_up is no longer
    read-only (without peek it moves the connection's "last catch_up" marker; read-only connections still call it),
    and update_row is destructive (it overwrites values; null clears). more_tools(tool=…) prints the tool's true
    hints after its name (readOnly, destructive, idempotent). tools/list leaves out hints equal to the MCP
    defaults (a read-only tool lists readOnlyHint and openWorldHint; a write tool destructiveHint, openWorldHint
    and idempotentHint when true). Tool names, descriptions and schemas are unchanged.
  • Project site (site/) rewritten for 0.20. The first screen is about agents and MCP: quick start, connecting,
    real find_context and patch_section output with the measured numbers, suggestions and ranges. The language
    switch goes to a page per language and works from file:// too. The version is read from
    apps/server/package.json at build time. llms.txt and links to each document's Markdown source. 0.20
    screenshots and a new intro video.

Fixed

  • Public links: a callout shows as in the editor, its type's icon and then the text, with line breaks, inline code,
    bold and links flowing inside the tinted box. Since 0.12.0 the text took the icon's place and stood in narrow
    side-by-side columns that ran out of the box (and widened the page on phones) (docs/adr/2387-*).
  • Public links: each callout type has its own tint again (note, tip, warning, danger, info), not the note blue for
    all (docs/adr/2387-*).
  • Public links: text colour and background colour, on words, whole blocks and table cells, show as in the editor in
    the light and dark themes; printed or saved as PDF they use the light colours (docs/adr/2387-*).
  • A section patch that the server refuses no longer shows up as an unhandled promise rejection in the server log
    (gatedTransact, docs/adr/2424-*).
  • Documentation: deploy/DEPLOY.md gives the language menu as Settings › Appearance › Language and the sign-in link
    as "Forgot your password?", writes every menu path with ›, says plainly why plain HTTP (3-A) is for testing only,
    and ties deploy/local.sh's missing setup link to an image older than 0.17 instead of an unpublished one.
    docs/BACKUP.md names SHA256SUMS as the file a tamperer would have to rewrite. docs/OPERATIONS.md points at the
    BACKUP.md sections that exist, gives effective_cache_size as at most PG_MEM_LIMIT minus shared_buffers (as
    both example columns already were), says that edits made offline are kept on the device when offline copies are
    on, that it is a new VAPID key (not APP_SECRET_KEY) that voids push subscriptions, who a "manager" of public
    charts is (a workspace owner or admin), and that deploy/local.sh makes a hex POSTGRES_PASSWORD and a base64
    APP_SECRET_KEY. The user guide and docs/MCP.md say what the untrusted-content marking does not do: it helps an
    agent tell notes from instructions but does not stop an injection by itself; read-only connections, ranges, edit
    locks, suggestions and version history are what limit an agent. The Korean files carry the same fixes.

Performance

  • Web bundle against 0.19.1 (365b664), both built from git archive and measured back to back: entry index-*.js
    447,198 → 449,412 B (122,995 → 123,356 B gzip); entry plus modulepreload 1,374,102 → 1,381,039 B (404,604 →
    406,213 B gzip); entry CSS 19,717 → 20,944 B gzip (column, public callout and colour styles); the column code sits
    in the editor chunk (CollabEditor, 126,070 → 130,001 B gzip, after the chart adapter left it); precache 107 → 109
    entries, +36,890 B (docs/PERFORMANCE.md).
  • Public charts (docs/adr/2442-*): a public page with charts loads PublicChartMount (1,392 B gzip) and its CSS
    (226 B), the chart adapter (961 B) and ChartRender (50,822 B, the app's chart chunk) only when the page has a
    chart; a page without charts requests none of them. The share dialog's chart count of a folder link with 300 large
    pages that all hold a chart takes about 0.36 s (26 ms with one chart page) (docs/PERFORMANCE.md).
  • MCP tools/list with the annotations (scripts/mcp-tools-list-cost.ts, read-write connection, no database): full
    48 tools 51,059 → 52,932 characters, ~12,777 → ~13,245 tokens (+468, +3.7%); core 32 tools 30,093 → 31,391
    characters, ~7,533 → ~7,857 tokens (+324, +4.3%). Listing all four hints on every tool would have cost +960 / +641
    tokens. Server instructions unchanged (1,965 characters, ~492 tokens) (docs/PERFORMANCE.md).
  • find_context latency with the new word rules is unchanged (p50 36.2 → 34.6 ms, p95 102.2 → 90.8 ms on 15.8k
    sections, interleaved runs). The document schema guard costs current clients one comparison per message; on the
    server a keystroke costs nothing measurable and a new block in a 2,000-block group about 50 µs
    (docs/PERFORMANCE.md).
  • Measured and not adopted: semantic search with multilingual-e5-small and the role prefixes above, fused by the
    0.20 code as it is. With 5,000 extra pages, page@1 on the held-out questions went 0.848 → 0.939 but on the tuning
    questions 0.867 → 0.844; on the private check 0.944 → 0.917 (page@3 0.972 → 1.000). Answers took 1.7× (private) to
    7.5× (benchmark) the tokens, and each question 33–40 ms more at p50. Nothing changes in the code or the defaults
    (docs/PERFORMANCE.md, "Rejected / no effect").