fix(ui): 0.32.0 adoption feedback (default KaTeX loader, docs, HANDOFF in tarball) - #1399
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Default KaTeX loader isolated. The default
import('katex')moves out ofutils/mathinto its own module,utils/math-default-loader(loadDefaultMathRenderer), andutils/mathnow keeps the host loader asnulluntil 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 aliasesmath-default-loaderat 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.tsnow pins the split (noimport('katex')site inutils/math, the only one inutils/math-default-loader); the built-bundle registration and presence markers are unchanged.onUnanchoredChangetiming 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.projectHostThreadsdocumented as HTML-only: the projection pinsblockIdto"", offsets to0, and carries nostartMeta/endMeta. Markdown support was not added: the markdownViewerrestores byblockIdplus 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.maxAdditionalTargetsdocumented: with the cap enforced upstream (bridge toggle, parent trust boundary on submit and restore,maxTargetson 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.Packaging:
HANDOFF.mdjoins the packagefiles, 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 typecheckclean;bun test packages/ui729 pass, 516 skip (DOM-gated), 0 fail;DOM_TESTS=1on MathBlock.firstPaint, InlineMarkdown and math tests 44 pass;build:reviewandbuild:hooksucceed andtests/entry-assets.test.tsruns 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.