Skip to content

fix(ui): 0.32.0 adoption feedback (default KaTeX loader, docs, HANDOFF in tarball) - #1399

Merged
backnotprop merged 2 commits into
mainfrom
fix/ui-0.32-adoption-feedback
Aug 27, 2026
Merged

fix(ui): 0.32.0 adoption feedback (default KaTeX loader, docs, HANDOFF in tarball)#1399
backnotprop merged 2 commits into
mainfrom
fix/ui-0.32-adoption-feedback

Conversation

@backnotprop

Copy link
Copy Markdown
Owner

Follow-up to the 0.32.0 adoption of @plannotator/ui by a host (Workspaces), which reported five mismatches. Additive only; Plannotator's own behavior is unchanged (its entries fill the math slot through math-eager before the first render, so the changed branch is never reached there). No server changes.

  1. Default KaTeX loader isolated. The default import('katex') moves out of utils/math into its own module, utils/math-default-loader (loadDefaultMathRenderer), and utils/math now keeps the host loader as null until one is registered: the default is called only on the null branch, and a registered loader is never backfilled by it, not even after the host's load rejects (new unit test; the existing default path also gained a test since the split is what wires it back in). Honest limit, measured on a scratch Vite 6 consumer of this checkout: chunk emission is static, so a host build that registers a loader still emits the package's 484 KB katex chunk (never requested) unless it aliases math-default-loader at a stub. With that two-line alias the same build emits zero chunks carrying the KaTeX body; without a loader the chunk is emitted and requested as before. The alias recipe and the measurement are in HANDOFF.md "Lazy renderers and eager entries". tests/entry-assets.test.ts now pins the split (no import('katex') site in utils/math, the only one in utils/math-default-loader); the built-bundle registration and presence markers are unchanged.

  2. onUnanchoredChange timing documented in README and HANDOFF: nothing is delivered for a document before the bridge's first post-restore report, per reload generation; a prop-side change before that point folds into that report, so a host must not gate on a prop-side delivery arriving first.

  3. projectHostThreads documented as HTML-only: the projection pins blockId to "", offsets to 0, and carries no startMeta/endMeta. Markdown support was not added: the markdown Viewer restores by blockId plus text search inside that block, so a metas passthrough alone would never re-anchor a markdown thread; markdown threads still need the host's own projection.

  4. maxAdditionalTargets documented: with the cap enforced upstream (bridge toggle, parent trust boundary on submit and restore, maxTargets on read), a host's cap-dropped handling is unreachable in normal operation and is a backstop only; byte-budget drops remain a separate, reachable path.

  5. Packaging: HANDOFF.md joins the package files, so README's "See HANDOFF.md" references resolve in an installed copy. bun pm pack --dry-run: 362 to 363 files, unpacked 4.67 MB to 4.75 MB (the 86 KB HANDOFF plus the 1.2 KB loader module).

Verification: bun run typecheck clean; bun test packages/ui 729 pass, 516 skip (DOM-gated), 0 fail; DOM_TESTS=1 on MathBlock.firstPaint, InlineMarkdown and math tests 44 pass; build:review and build:hook succeed and tests/entry-assets.test.ts runs its built-bundle marker checks 24 pass, 0 fail; the scratch Vite consumer builds in all three variants (no loader, loader, loader plus alias).

AI-assisted (Claude) under maintainer direction.

…ship HANDOFF.md, document three contracts

- utils/math: the default import('katex') moves to utils/math-default-loader
  and is called only while no host loader is registered; a registered loader
  is never backfilled by it. Its own module lets a host alias the chunk away.
- README/HANDOFF: onUnanchoredChange delivers nothing before the bridge's
  first post-restore report per generation; projectHostThreads is HTML-only;
  a host's cap-dropped handling is a backstop once maxAdditionalTargets is
  enforced upstream.
- package.json: HANDOFF.md joins the tarball so README's references resolve.

AI-assisted (Claude) under maintainer direction.
…flight default load, widen katex site regex

- README/HANDOFF: a projected COMMENT with quoted text still re-anchors on
  the markdown Viewer by whole-document text search; what blockId "" and
  offsets 0 actually lose is export ordering, the lines N-M label, repeated
  text disambiguation and the no-flash meta restore.
- Loader docs: a default KaTeX load already in flight at registration still
  fills the slot (pre-existing), so register before the first math render.
- entry-assets: match either quote style for the import('katex') site.

AI-assisted (Claude) under maintainer direction.
@backnotprop
backnotprop merged commit e807e2b into main Aug 27, 2026
28 checks passed
backnotprop added a commit that referenced this pull request Aug 27, 2026
Version bump, lockfile refresh, and docs pass for the ui 0.33.0 release carrying the bridge-as-asset seam (#1398) and the 0.32.0 adoption feedback fixes (#1399). Core stays 0.25.0.

AI-assisted (Claude) under maintainer direction.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant