Repository navigation
Adopt this repository into the paranext organization - #1
Conversation
This repo is now maintained at paranext/scripture-editors and is the source of truth for the editor packages. It carries the full history of eten-tech-foundation/scripture-editors, its MIT license, and its attribution, but it is deliberately not a GitHub fork: while a repository is a fork, GitHub always defaults new pull requests to the parent and offers no setting to change that. Documents what that means in practice: - Where this repository lives, and its relationship to paranext-core — which builds these packages from source and stages them rather than installing them from npm, so this repo's package.json files are authoritative for its own dependencies. - Why the platform-yalc branch still exists. The name is historical, but its coordination role — letting a breaking change land on main before build servers pick it up — is not. - How to set up the eten-tech-foundation remote, pull from it, and contribute back, so that option survives even though we do not track it. - How to move branches, tags, and open PRs across from the other repository, since this one was seeded with a curated ref set rather than a full mirror. Replaces the npm-publishing machinery with a release process modeled on paranext-core's. Consumers pin a revision of this repository, not a published version, so a release is a repository tag and one tag pins both packages. Adds a bump-versions script, workflow, and composite action, plus a publish workflow that verifies the requested version matches the manifest before tagging. Removes the scribe publish workflow and the tag-triggered npm publish and auto-bump jobs. Drops the Nx Cloud references. There is no account for this organization, and the caching does not earn standing one up. Adds a SIL Global and United Bible Societies copyright line alongside ETEN Tech Foundation's. The license stays MIT, which is what keeps contributing back possible.
…pushes paranext-core's package-lock.json records these packages' dependency closure, so a dependency added, removed, or re-ranged here breaks every core build the moment platform-yalc moves — core's `npm ci` refuses to run until its lockfile is refreshed. That refresh is a one-command PR in core, but nothing reminded the person moving the branch to open it. Adds a workflow that runs on every push to platform-yalc: it recomputes what core's lockfile should record from this repo's manifests (applying the same transforms core's staging applies — devDependencies dropped, workspace: specifiers rewritten to the sibling staged folder, the package list read from core's own dev-packages.json so the repos cannot drift) and passes when core's main matches. When it does not, it scans open core PRs touching package-lock.json for one that brings it in sync — the refresh being in flight is fine — and otherwise fails with the exact commands to fix it. Version-only bumps pass untouched; npm ci does not check the version of a file: dependency, so releases need no core PR. The README's platform-yalc section documents the same flow for humans. Verified against live data: the in-sync path against the core PR branch, and a fabricated dependency change exercising the mismatch diff, the open-PR scan (152 open PRs, paginated), and the failure instructions.
ec221be to
75adc47
Compare
The workflow catches a missing core lockfile PR after the push; this catches it before. Operates on a temporary branch from origin/platform-yalc (never the often-stale local branch), restores the original checkout on exit, aborts cleanly on rebase conflicts, and runs the same verify-consumer-lockfile-sync check the CI workflow runs. --dry-run stops short of pushing; --skip-verify is the documented emergency hatch.
75adc47 to
b3b88d4
Compare
paranext-core consumes these packages by copying them out of a checkout rather than installing them from a registry, so until now every core developer needed this repo's toolchain — pnpm, nx, a full vite build and api-extractor run — during `npm install`, just to run Platform.Bible. That build is also where a whole class of install failures lives. Committing dist reduces the consumer's work to a copy. Only people changing the editor build it. The obligation this creates is that dist can go stale against src, and a stale dist is invisible in review: the source diff looks right while consumers get old code. CI now rebuilds and fails if the committed output differs (scripts/verify-committed-dist.mjs). Every published artifact is byte-deterministic — verified by rebuilding and comparing hashes — so the check is exact rather than advisory. Also stops packing dist/*.tsbuildinfo. That is TypeScript's incremental cache, the one non-deterministic file in the build, and it was being copied into consumers' staged copies as though it were a shipped artifact.
|
Added: the built
Guarding the obvious risk (a stale
Two things reviewers should know:
|
A --stat summary cannot distinguish a genuine source change from a build that is not reproducible across machines, which is exactly the question a CI failure here raises.
nx declares `dist` a cached target output, and earlier steps in this job populate that cache, so a cache hit restores nx's copy over the committed one — the check would then be grading the cache instead of the source. It also explains an earlier spurious failure of this step: the first run after committing dist rebuilt over it incrementally.
…tput The first dist commit captured a mid-build state: tsc's per-file declarations under dist/converters/ plus an index.d.ts that merely re-exported them. api-extractor consumes those and emits the rolled-up API surface as index.d.ts, then removes them — so which files exist depended on which nx targets last ran, and CI's freshness check failed against a local build for exactly that reason. Commits what a canonical build leaves: the rolled-up index.d.ts and the bundles. The intermediate per-file declarations are gitignored, since whether they are present is not meaningful and nothing references them — `types` resolves to dist/index.d.ts.
Same class of intermediate artifact: api-extractor rolls the declarations into dist/index.d.ts and the map beside them becomes meaningless, but a plain `build` leaves it, so its presence depends on which targets last ran. CI caught it as an untracked file.
`homepage`, `repository`, and `bugs` still named eten-tech-foundation, so everything npm derives from them — the repository link on npmjs.com, `npm repo`, and the "report an issue" link — sent people to the repository this one replaces. The package names and their `@eten-tech-foundation` scope are deliberately unchanged: publishing continues under that scope, and renaming would break every consumer. Only the location of the source moves. `packages/scribe` is left alone; #2 removes that package. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017jvJ2eYTfxJaBkKoQbVeiW
`publish.yml` created the release tag after nothing but a build. The workflow it replaced gated every publish on `needs: test`, and the committed-dist check lives in `test.yml`, which only triggers on `main` — so a release cut from any other branch was verified by nothing, and a tag cannot be un-cut. Run the same checks `main` gets, all of them before the release step. The bump step after the release could never have worked: `actions/checkout` cleans the workspace, which takes `node_modules` with it, and the composite action then runs `tsx`. By that point the tag exists and `bump-versions` is not idempotent, so the failure has to be unpicked by hand. Reinstall first. `verify-consumer-lockfile-sync.mjs` compared `dependencies` and `peerDependencies` only. `peerDependenciesMeta` is what marks a peer optional, so deleting an entry makes that peer required and npm pulls it into the closure: verified against a staged `file:` dependency, making `yjs` required this way fails every core `npm ci` with "Missing: yjs from lock file" while both dependency lists read identically. Compare it too, structurally, since its entries are objects. That guard also spent one API request per open core PR — 154 today — to decide which touch the lockfile, which exhausts the anonymous rate limit it runs under locally. Look at recently-updated PRs first and walk the rest only when the alternative is failing. A file list at the page limit now counts as a candidate rather than being read as "no lockfile here", a deleted head fork is skipped instead of throwing, the raw.githubusercontent reads authenticate like the API reads, and an empty `CORE_BRANCH` falls back to `main` instead of building a malformed URL. `verify-committed-dist.mjs` capped its failure output at 200 lines, which bounds nothing when `index.js.map` is three megabytes on one line. It also now records the blind spot it cannot cover on its own — `git status` sees no ignored path — and points at #5. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
`nx.json` still carried ETEN's Nx Cloud access token and workspace id, disabled only by an underscore on each key. Nx Cloud is off for this repo and the credentials are not ours; remove them. Its `sharedGlobals` also named `.github/workflows/ci.yml`, which this repo has never had, so no workflow change has ever invalidated a cached target — point it at `test.yml`. paranext-core consumes these packages by staging a built copy out of a checkout, so `yalc` has no remaining role: drop the dependency and the `devpub` scripts, and replace both "Develop in App" sections with the flow that works now (`npm run build:editor` in core). Badges pointed at the old organization and at `test-publish.yml`, which no longer exists, and showed an npm version for packages that are not published to npm — a repository tag is what pins them. Two docs named that workflow too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
`test.yml` ran on `main` only, so a release cut from `release-prep` or a `hotfix-*` branch had no formatting, lint, typecheck or test run against it anywhere. paranext-core covers those branches in its own test workflow and therefore runs no checks at publish time; this repo had the triggers narrower and the gap sat in the middle. Widen the triggers instead of duplicating the checks into `publish.yml`. The committed dist stays checked at publish, because core has no equivalent of it: a tag is where consumers copy their editor from, a tag cannot be un-cut, and a stale dist inside one looks like nothing at all. `extract-api` is the build, so it replaces the separate build step rather than adding to it. The post-release checkout now uses `clean: false`, matching core, rather than reinstalling — and only runs when the bump ref actually differs from the branch already checked out. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
…efreshes Deciding whether one open core PR touches `package-lock.json` costs an API request, and core carries 150+ open at a time. Run locally by `move-platform-yalc` there is no token, so the scan exhausted the 60/hour unauthenticated limit and failed the check exactly when it mattered. A lockfile refresh for the change being pushed is worked on alongside it, so PRs untouched for two weeks are not it. `move-platform-yalc --skip-verify` remains the escape hatch if that ever stops being true. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
The failure told you to refresh core's lockfile and open a PR, which is right when the refresh does not exist yet. It said nothing about the case where it does and this did not find it — the PR has gone untouched past the search window, or the two changes are being landed together on purpose — leaving the escape hatch discoverable only by reading the script. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
…d at Core carries 155 open PRs, nearly all stale. Measured against it, a 7-day window selects 51 and a 14-day window 60, against an unauthenticated budget of 60 requests an hour — 7 days fits with room for the listing calls, 14 does not. The failure line also reported three bare numbers with no way to tell what they counted, which read as though most PRs had been skipped. Say plainly how many were examined, how many exist, and how many of those examined touch the lockfile. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XqqozB7YdhQFin63R2gBpL
- `bump-versions-action` and `publish.yml`'s version check spliced `workflow_dispatch` inputs
straight into bash via `${{ }}`. They now arrive through `env` and quoted expansions, so what
someone types cannot become shell.
- `COMPARED_SECTIONS` omitted `optionalDependencies`. npm records it for a staged `file:` package
and pulls its entries into the closure, so adding one would pass this check and then fail every
paranext-core `npm ci` — the breakage the check exists to catch.
- `CLAUDE.md` and `docs/dependency-updates.md` still routed maintainers through `nx devpub`, which
this change removes from both published packages. The packing gate is now the `npm pack --dry-run`
paranext-core's staging step actually calls, so a break there is a break here.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
…ble temp path The verify-script snapshot went to `$TMPDIR/verify-consumer-lockfile-sync-<pid>.mjs` and was then executed. Pids are small and enumerable, `copyFileSync` follows an existing symlink, and there is a window between the write and the run — so on a shared machine another local account could have this script execute their code inside a checkout that is about to be force-pushed. It now writes into a 0700 `mkdtemp` directory and removes the whole directory afterward. `git rebase --abort` also ran unguarded inside the rebase's own catch. A rebase that fails without starting — an unreachable `origin/main`, or a leftover rebase directory — makes the abort fail too, and that throw escaped over the conflict message: the operator saw `Command failed: git rebase --abort` instead of the real cause, and was told the branch was back at origin's state when the reset above had already moved it. The abort now has its own try, and the fallback reports the original rebase error and where the checkout actually is. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
…-run - `verify-consumer-lockfile-sync` read core's files through raw.githubusercontent, which serves `max-age=300`. The recovery this check prescribes — land the core lockfile refresh, then re-run — could therefore still be answered from the pre-merge blob, while the open-PR fallback no longer matched because that PR had just closed, leaving `--skip-verify` as the only way out of a problem already fixed. The contents API serves the same bytes at `max-age=60`; the raw media type carries a lockfile past the 1MB cap on the JSON representation. - It also folded every repo in core's `dev-packages.json` into one list and resolved each `packagePath` against this checkout. A second dev repo would make it read manifests that are not here. It now selects this repo's entry by `folder`, which is stable across the org move in a way `cloneUrl` is not — matching on the URL would have replaced the accurate "that core branch predates staged-dependency consumption" message with a wrong one for the whole transitional window. - `bump-versions` ran `git checkout -b` and `git commit` unconditionally, so a re-run (branch exists, exit 128) or a publish whose post-release version equals the released one (nothing staged, exit 1) failed after `publish.yml` had already cut the tag — which cannot be un-cut. It now uses `-B` and skips the commit when the manifests already say the new version, so the step the workflow's own comment called "unpicked by hand" is re-runnable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
rolfheij-sil
left a comment
There was a problem hiding this comment.
🤖 Claude: Scope note first, for Matt and TJ: this PR got one AI review pass plus a handful of spot checks by Rolf, not the adversarial re-verification we gave paranext-core#2745, studio#179 and the eight extension PRs — so weight it accordingly, and please don't read "no blockers" as "thoroughly proven". The one thing I did verify mechanically: the committed dist (5 + 6 files, ~4 MB) matches files/.gitignore exactly with no .tsbuildinfo, verify-committed-dist.mjs is byte-exact and runs on every PR and before tagging, bump-versions.ts leaves the workspace:~ specifier alone (that path is live), move-platform-yalc.mjs refuses dirty trees/local-only commits and uses --force-with-lease, and CI is green on the tip.
No blockers. Notes, most useful first:
- Tag scheme — keep yours. One repo-level
v<platform-editor version>is the honest unit because consumers (core'sdev-packages.json, studio'sproductInfo.json) pin one repository revision for both packages; per-package tags would imply an independence the consumption model doesn't have, and the publish event that justifiedplatform_v*/utilities_v*is gone. One gap: the tag doesn't disclose the utilities version — havepublish.ymlput it in the release body (readpackages/utilities/package.jsonin the workflow). move-platform-yalclocally hits the anonymous rate limit.verify-consumer-lockfile-sync.mjssizes its 7-day window against the 60 req/h unauthenticated budget (its own comment says ~51 PRs), butnpm run move-platform-yalcis the documented local command andGITHUB_TOKENisn't set outside Actions. A 403 currently surfaces as a bareGET … -> 403 Forbidden(fetchJson, L52–56). Suggest catching 403 and telling the caller toexport GITHUB_TOKEN=$(gh auth token), and saying so in the README section.- #1 and #2 conflict with each other (confirmed with
git merge-tree):README.md(the link-reference block you edit vs the scribe lines #2 deletes) andpnpm-lock.yaml. Whichever merges second needs a manual resolve + lock regeneration — not a rebase-clean situation. - Manual npm-publish path is still fully wired:
.npmrc(_authToken=${NODE_AUTH_TOKEN},always-auth), both packages'publishConfig+prepublishOnly/postpublish, andscripts/prepare-publish.ts. CI no longer calls it, but anyone with scope rights could stillpnpm publishby hand. Given the "no npm publishing" decision, either remove it or note in the README that it's deliberately kept. - README "Releasing" steps 2/4 say "merge the
bump-versions-<version>branch" —mainis protected, so that's "open a PR from it"; the old flow auto-opened one, the new composite action only pushes the branch. - Repo hygiene vs the ticket (not this PR's job, but unowned today): no
CODEOWNERS(named in PT-4500 item 3),delete_branch_on_mergeis off (core has it on), rulesets empty (classic protection is on; details need an admin), the Reviewable badge is in the PR body but the app isn't installed on this repo, and the_nxCloudAccessTokenyou remove fromnx.jsonhas been in upstream's public history for a long time — worth a quick "is it inert?" with whoever owns that Nx Cloud account. - The workflows are unexercised, as you say — a single
workflow_dispatchofbump-versionsandpublishon a test tag (or a fork) before the first real release would be the actual test.
One design question that spans both repos (also raised on paranext-core#2745): this PR mints v<version> tags, but the consumers still pin the force-pushed platform-yalc branch, and this repo carries the machinery to keep that branch in sync with core (verify-consumer-lockfile-sync.mjs, move-platform-yalc). If consumers pinned the tags this release process creates, that machinery and the branch itself could retire — a bump would be a core PR changing the pin and the lockfile together. Asking here because it changes what this repo's release process needs to guarantee (nothing more than "tag = built dist matches source", which publish.yml already checks).
Three workflows set up Node 20 while `package.json`'s Volta pin — the version every developer runs — is 22.22.0. That gap matters most in `publish.yml`, which rebuilds `packages/*/dist` and compares it against the committed copy before cutting the release tag consumers copy their editor out of: any Node-sensitive difference in that output either fails the comparison with a diff nobody can reproduce locally, or, where the difference is invisible to it, ships bytes no developer ever ran. `node-version-file: 'package.json'` makes setup-node read the Volta pin, so the three stay in step with local development by construction. The repo declares no `engines`, so the pin is what it resolves. `test.yml`'s matrix loses its node dimension, which only ever held one value. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
The 403 handling added earlier covered only half of what it needed to. GitHub answers a rate limit with 403 **or** 429: the primary limit zeroes `x-ratelimit-remaining`, a secondary limit sends `retry-after` instead, and the 429 form of both was not matched at all. The `!GITHUB_TOKEN` fallback also labelled every unauthenticated 403 a rate limit, including a genuine permissions failure — it now says so hedged rather than confidently wrong, since a token is the right advice either way. Verified across nine response shapes: both statuses with each header, a permissions 403 with a token and requests remaining, 404, 500, and a bare 403 with and without a token in the environment. The README half of that review point was missing entirely. The section on moving `platform-yalc` now says the check spends tens of requests against the 60-an-hour anonymous budget, that Actions sets `GITHUB_TOKEN` but a local run does not, and gives the one line that fixes it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
|
Correcting my earlier reply on note 2 (the anonymous rate limit) — I reported it done, and only half of it was. Both halves are now in What was missing: you asked for the 403 to be caught and for the README to say so. I did the first and skipped the second without noticing; the README section on moving And the detection was too narrow. Checking GitHub's actual behaviour rather than assuming: a rate limit comes back as 403 or 429, the primary limit zeroes Verified across nine response shapes: 403 and 429 with each header, a permissions 403 with a token and requests remaining, 404, 500, and a bare 403 both with and without a token in the environment. The check still passes end to end with and without a token. |
The section a reader reaches first when asking how to move this branch gave the raw `git rebase && git push --force-with-lease` sequence, and only mentioned `move-platform-yalc` further down under dependency changes — so the guards were documented somewhere other than where the question gets asked. It now leads with the script and what it refuses (another branch, a dirty tree, commits only on your machine, a lockfile that no longer matches), and links to the existing section for the check, its flags, and the token. The hand sequence stays only as what skipping it costs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
paranext-core builds these packages only when the pinned revision has no committed `dist/` to copy. Saying it "builds them from source" describes the fallback as if it were the path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
`verify-consumer-lockfile-sync` threw when core's `dev-packages.json` had no `packagePath`/`stagingFolder`, with a message saying "there is no lockfile contract to verify against it" - a no-op reported as a failure. That is core's `main` today, and stays so until the staged-dependency change lands there, so every push to `platform-yalc` fails and `move-platform-yalc` refuses to push. The only way through is `--skip-verify`, which also disables the checks that DO apply once it lands. It now logs the reason and passes. Deliberately not extended to core PRs: the `packagePath` and `stagingFolder` read from the branch are what locate the manifests and name the lock entries, so a run that cannot read them cannot compute what to compare against a PR either. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDvvB9RpsxEE49f75ZtB6
`etc/<package>.api.md` is API Extractor's report on the public type surface. It is committed so that a public API change — an added export, a changed signature, a removed type — arrives as a readable diff in the pull request that makes it, rather than buried in a rolled-up declaration bundle. Nothing kept it current. `extract-api` runs api-extractor with `--local`, which rewrites the report rather than failing on drift, and neither half of the safety net named `etc/`: the README's `git add` line listed only the two `dist` paths, and the verifier scoped its `git status` to the same two. So changing a public API and following the README committed a fresh `dist` alongside a stale report, and CI passed — it regenerates `etc/` on every run and then looks away. Add both `etc/` directories to the check and to the README, and rename the constant, the messages, and the section heading to say "build output" now that they cover more than `dist`. The heading rename moves its anchor, so the in-page link to it moves too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012F9WPtSNrcpEAfFdu3trBw
`pnpm nx run-many -t extract-api` — what CI ran, what the README told you to run, and what the freshness check's failure message printed — finishes with `packages/utilities/dist/index.d.ts` holding tsc's 13-line re-export stub instead of api-extractor's 648-line rollup. `packages/platform`, `libs/shared`, `libs/shared-react` and `libs/test-data` each carry a TypeScript project reference to `packages/utilities`, so their `build` emits utilities' declarations into utilities' own `outDir`. That write happens below nx's task graph: `build` dependsOn `^build` and `extract-api` dependsOn only its own `build`, so nothing orders `utilities:extract-api` against `platform-editor:build`, and whichever writes last wins. CI has been passing on scheduling luck — the runner happens to overlap the two so the rollup lands second. A pristine clone here loses that race every time, which means following the documented steps committed a broken type surface: that stub re-exports `./converters/**`, the shape that collided xmldom in paranext-core. Extract one package per nx invocation, dependents before the packages they depend on, so the last write is always an `extract-api`. Cache phasing was tried first and does not work — `platform-editor:build` misses the cache and re-runs. `scripts/published-packages.mjs` holds the ordered list and the rationale, and is now the single source for the verified paths too, so the rebuild order and the checked paths cannot drift apart. Issue #5 removes the need for any of this ordering; until then the script is the only supported way to rebuild. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012F9WPtSNrcpEAfFdu3trBw
… the note A browser reading back a caret at the end of a line a note ends resolves it to the end of the note's closing glyph, so the next keystroke became `\f*Z`: invisible in a collapsed note and dropped from the USJ in every view. Tier 1 already splits text typed after a char span's own closer out of the span; the same split now covers a note's own closer. That covers clicking at the end of such a line in Unformatted view and typing after closing a note that ends an unclosed char span (lyonsil round 13 follow-ups #1 and #5). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ocused applyUpdate (#15) * feat(platform): EditorRef.getNoteIndex/getNoteKey map between note keys and document-order indexes Adds $getNoteIndex to shared-react's note.utils (a DFS over note nodes, reused by ImmutableNoteCallerNode's existing getNoteIndex so both paths share one implementation) and exposes it plus its inverse as EditorRef.getNoteIndex/getNoteKey. This is the coordinate bridge a footnotes pane needs: the host addresses notes by the document-order index a USJ walk yields, while the editor identifies them by Lexical node key. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * fix(platform): delegate getNoteIndex/getNoteKey in Marginal and complete getNoteKey TSDoc MarginalRef extends EditorRef, and Marginal.tsx builds its useImperativeHandle object by hand, so the two new EditorRef members need matching delegations there, following selectNote/getNoteOps. Also adds the missing @PARAM noteIndex to getNoteKey's TSDoc. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * feat(platform): EditorRef.highlightNote applies PT9's selected-caller border NoteCallerHighlightPlugin keeps `caller_highlight` on exactly one note's caller element, re-applying it after every commit because Lexical recreates the caller DOM on a collapse toggle. The class is set imperatively, never through node state, so a highlight cannot dirty the document. The highlighted note is tracked by key. A commit that destroys it keeps the highlight only for an in-place replacement — replaceEmbedUpdate re-keys the note it rewrites — recognized as a note created in the same commit at the destroyed note's document-order index. A note that left the document, or a wholesale load (EXTERNAL_USJ_MUTATION_TAG) whose fresh notes are a different chapter's, drops the highlight instead of sliding it onto an unrelated note. The caller is found among the note's children rather than as its first child: in editable marker mode a note opens with its marker glyph. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * docs(platform): state highlightNote's two silent no-op modes The public TSDoc promised a highlight without naming the two paths where none appears and nothing is reported: a note BUILT expanded under editable marker mode has a plain-text caller instead of the immutable caller element the style attaches to, and the note is resolved eagerly with no retry, so a call made before the document has loaded or with a stale key or out-of-range index is discarded and clears any highlight already showing. Both sentences go on EditorRef.highlightNote and on the plugin handle's setHighlightedNote, where the behavior lives. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * build(platform): rebuild dist and API report for getNoteIndex/getNoteKey/highlightNote Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * fix(platform): never pull DOM focus into an unfocused editor on applyUpdate Lexical reconciles the DOM selection after every commit, and writing a selection inside a contenteditable focuses that element as a browser side effect. A programmatic applyUpdate therefore stole the caret from whatever the user was actually typing in - most visibly a host's inline note editor applying its live edits back into the Scripture text, which blurred one debounce interval after the first keystroke. Tag the commit with Lexical's SKIP_DOM_SELECTION_TAG when this editor's root does not contain the active element. A focused editor still reconciles, so a collaborator's op keeps the local caret in the right place. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * docs(platform): record the note index/highlight API and the focus fix Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * test(platform): poll for the second session's char node in the reopened-palette test Space commits the typed marker literal at once, but the char node it becomes settles afterwards; the assertion read it synchronously and failed under CI load (the palette itself reopens, filters, and commits correctly after any delay). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cexoio1HtVmuAp2zJQKK3g * feat(platform): place a note caret by content offset, and just after a note Two host-facing caret placements a footnotes pane needs. selectNoteTextOffset lands at an offset over a note's CONTENT text, skipping every display artifact the view adds around it - marker glyphs in either marker mode, attribute display runs, engine-owned NBSP spacers, an opening glyph's NBSP separator prefix, and an expanded editable note's caller. A host that captured a click position over its own rendering of the same note now resolves to the same character whatever markerMode this editor renders in, which a host-side DOM walk cannot do: under markerMode "editable" a glyph is real text inside the char span and the span's first text child carries the separator as a prefix, neither of which a per-node DOM filter can drop. selectAfterNote parks the caret immediately after a note - past its caller in a collapsed note. Like applyUpdate, it carries SKIP_DOM_SELECTION_TAG when this editor's root does not hold DOM focus, so a host can set it while the user keeps typing in a note editor elsewhere; that rule now has one name (holdsDomFocus) rather than two copies. Also polyfills Range.getBoundingClientRect for jsdom, which Lexical measures through whenever it scrolls a collapsed caret into view after a commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013PLV1rbFoxTNwRtwfoUTdk * fix(platform): keep the Range rect polyfill out of the shared test setup markerMenuContext.utils.test.tsx asserts that a missing Range rect is exactly what leaves anchorRect undefined headlessly, so polyfilling Range.getBoundingClientRect globally made that behavior untestable. Install it only in the caret-placement suite that needs it, and restore the original afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013PLV1rbFoxTNwRtwfoUTdk * refactor(shared-react): break the note-index import cycle with a leaf module ImmutableNoteCallerNode needs $getNoteIndex, and the note machinery in note.utils needs ImmutableNoteCallerNode, so the two imported each other. That works only for as long as every use stays inside a function body; the first module-level use - or a CJS evaluation order that loads the caller node first - fails at load with an uninitialized binding. Move the index into note-index.utils, a leaf that imports neither, and re-export it from note.utils so callers keep finding it where they always have. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/9e7049b7-4943-4d56-b83c-1f99d89866e7 * fix(shared-react): keep the after-note caret out of a following glyph $selectAfterNote parked the caret at offset 0 of whatever text node followed the note, but a glyph text node's bytes are a picture of its own state - a verse number, a marker's syntax - so offset 0 is a position INSIDE the picture, which the next keystroke splits. That is exactly what $normalizeSelectionOutOfGlyphText exists to prevent, and a note ending a verse is followed by precisely such a node. Skip glyph text so those notes take the parent-offset branch instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/9e7049b7-4943-4d56-b83c-1f99d89866e7 * build: rebuild the committed platform dist for the note index and caret APIs This repository commits each published package's dist so paranext-core can copy it out of a checkout without running this toolchain, and the branch's editor changes had not been built into it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/d979f940-2a90-4191-8659-7d82e6558085 * fix(notes): address automated review findings on the note caret/highlight APIs Selecting an EXPANDED note that holds no content run at all (`\f + \f*`) was a no-op: `$selectNote`'s expanded branch selects the end of the last char child, and such a note has none, so the caret stayed outside the note and the next keystroke landed in the surrounding text. It now lands at the child slot content would occupy. `selectNoteTextOffset` documents that fallback, so the promise it makes now holds. Documentation that had drifted or was missing: - `selectNoteTextOffset` takes DOM focus where its neighbour `selectAfterNote` deliberately does not. That asymmetry is correct — it mirrors `selectNote`, which it falls back to, and its job is placing the caret in an editor the host is about to focus — but it was unstated, and the two neighbouring caret APIs read as behaving oppositely for no reason. Also records that the caret is placed, not revealed, while a note is collapsed. - `getNoteIndex`, `getNoteKey` and `highlightNote` now carry the `EXPERIMENTAL:` prefix every neighbouring note method has. - The caller highlight is a yellow fill AND thin blue borders, not just the borders; corrected in the model, the plugin and the changelog, with a note that a host vendoring its own `usj-nodes.css` needs the rule. - `holdsDomFocus` says why it is deliberately broader than `isFocused`. - The `$getNoteIndex` re-export's comment claimed a backwards-compatibility constraint that never existed; it now states the real reason (the barrel exports this file, not the leaf). `NoteCallerHighlightPlugin` imports the leaf directly rather than re-coupling to the heavy module. Tests: - The caret tests ran only under `noteMode: "collapsed"`, while the consumer's note editor runs expanded — a materially different interior where the caller is a plain TextNode and a `\cat` category becomes an attribute run. Both are documented behaviors with no coverage anywhere. Added an expanded block covering the caller skip, the `\cat` skip, a `\fp` paragraph-break crossing, and the no-content fallback (which is what found the defect above). - "does not mark the document dirty" asserted only that `onUsjChange` did not fire, which a node-state highlight producing identical USJ would also pass, and never checked that the highlight applied. It now counts commits and asserts the highlight landed. - The glyph-avoidance case asserted `not.toBe("verse")`, which passes for any other wrong placement; it now asserts the caret's actual position. - Added the missing positive pre-assertion to "clears when the note leaves". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/4c051464-cd5d-40f7-ab18-232f1c272d27 * refactor(shared): one reading of the opener separator's NBSP prefix How many leading code units of a text node are an opening glyph's display separator was worked out independently in three places: the note caret offset (`$noteDataTextStart`), `$selectCharContentStart`, and the collab emit path's note-content strip. markerSeparators.utils.ts already owns the convention and the predicate that builds the prefix, so the reading now lives there too, as `$separatorPrefixLength`: plain host text directly after a char-span opening glyph that starts with the NBSP. - The note caret offset and `$selectCharContentStart` call it directly. `$selectCharContentStart` used to skip ANY leading NBSP; every caller hands it the text straight after a span's opener, where the two agree. - The collab emit path keeps its narrower positional rule on top (only the span's own opener, its first child), so the ops it sends are unchanged. Adds unit tests pinning each guard in the helper (each was verified to fail a test when removed). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/e30d5c4e-6477-44a0-af88-da5bf2056809 * build: rebuild the committed platform dist for the separator-prefix helper Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/e30d5c4e-6477-44a0-af88-da5bf2056809 * fix(notes): resolve a highlighted note against an update still in flight `highlightNote` read the committed editor state, so an index resolved against the document as it was before any update still pending: a host that inserted or removed a note and then highlighted by index in the same turn marked the wrong note, or none. It now reads with `editor.read`, which commits pending updates first, as `getNoteIndex` and `getNoteKey` already do. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/62270ca3-4092-4411-a74c-f2fa9943757f * build: rebuild the committed platform dist for the in-flight highlight fix Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/62270ca3-4092-4411-a74c-f2fa9943757f * fix(notes): land in an empty note ahead of its display-only closer Selecting an expanded note with no content run (`\f + \f*`) lands the caret in the slot just before the note's closing glyph. The closer was found by looking for a closing marker node, which is what `markerMode: "editable"` builds. `"visible"` (the Markers view) builds the closer as display-only typed text, so it was not found and the caret went after `\f*` instead. The lookup now recognizes both shapes, and a test pins both marker modes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/131a9039-65c3-4bd1-9d12-987ea2fb1b8b * test(notes): let a fresh editor's mount-time caret land before placing one A fresh editor moves its caret to the start of `scrRef`'s verse a few microtasks after the document loads. The caret-placement tests sometimes acted before that move landed, so it overwrote the caret under test. "stays out of a glyph when the note is followed by one" failed about 3 runs in 8 this way. The render helper now waits a macrotask for the mount-time move before returning. 12 consecutive runs pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/131a9039-65c3-4bd1-9d12-987ea2fb1b8b * build: rebuild the committed platform dist for the empty-note closer fix Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/131a9039-65c3-4bd1-9d12-987ea2fb1b8b * fix(scrRef): keep a caret before a verse number in the verse before it Picking a footnote in the host's footnotes pane parks the Scripture caret just past the note's caller. When the note ends its verse — common, since a footnote usually hangs off the verse's last word — the next verse's marker follows the note directly, so that slot is also the slot the marker occupies. The host then publishes the note's own verse, and the plugin read the caret as being in the NEXT verse, treated the publish as a cross-verse navigation, and yanked the caret back to the start of the verse the user had just picked a note in. Two readings of "which verse is the caret in" had drifted apart: - `$getEffectiveVerseForBcv` counted a caret inside an editable verse marker as being past the verse number whenever the marker's text did not START with that number. Standard and Unformatted views render the whole marker (`\v 3 `) as the verse node's text, so every position in it — including offset 0, where a verse-final note leaves the caret — read as the new verse. The prefix now ends where the number does, wherever it sits. - `$moveCaretToVerseStart`'s "already here" guard read the verse off the caret's node alone, which is offset-blind, rather than through the resolution `$resolvePosition` reports positions with. It now asks the one question one way (I9), so the publish is recognized as a no-op. Navigating to the verse whose marker follows such a note still moves the caret, and is pinned alongside the two no-op cases. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f68e1e86-7eff-4dd8-9d54-d90693e2fd51 * build: rebuild the committed platform dist for the scrRef verse-boundary fix Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f68e1e86-7eff-4dd8-9d54-d90693e2fd51 * fix(notes): keep parked carets, resolve verses before a marker, count direct note text - selectAfterNote while unfocused: release the skip-DOM-selection tag after its selection-only commit (Lexical keeps such a commit's tags for the next one, so a later focus() focused nothing) and clear the stale DOM selection it left inside the editor, which the next event-less update read back over the parked caret. Same for applyUpdate's skipped write. New editorUpdate.utils: editorHoldsDomFocus (now shared by Editor and LoadStatePlugin), releaseTagsAfterNextCommit, clearStaleDomSelection, readLatest. - $getEffectiveVerseForBcv: a caret before a verse number reports the chapter's actual previous verse node (bridge, segment, omitted verse), falling back to number-1 only when there is none. $moveCaretToVerseStart asks $resolvePosition, so a heading before verse 1 (verse 0) is 'already here' too. - getNoteIndex/getNoteKey/highlightNote read the in-flight state when called from inside the editor's own update instead of committing (and freezing) it. - $selectNote lands ahead of an explicitly closed last run's closer; $selectNoteTextOffset counts text written directly in the note (excluding the caller explicitly) and skips glyph text such as an unmatched closer. - highlightNote falls back to the editable caller of a note built expanded; the highlight mutation listener skips its walks when nothing was created. - Cleanups: $getNoteIndex/$getNoteAtIndex on the lazy $dfsIterator; one $ownsOpenerSeparator predicate; $selectBreakPoint reads $separatorPrefixLength; one expanded-note bookkeeping helper in Editor; TSDoc calling-context lines; shared note EditorRef test helpers; tests read selection.focus and use the real $selectAfterNote. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * build: rebuild the committed platform dist for the note caret and verse fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * fix(editor): settle without taking focus back, and report a caret parked unfocused - commitPendingMarkerEdits follows applyUpdate's focus rule: called while another element holds focus, it skips the DOM-selection write (releasing the tag and clearing the stale DOM selection after). A host can then settle the text as the user moves into a note editor, instead of the idle settle moving focus back into the text a second later. - selectAfterNote reports the parked caret through onSelectionChange when it wrote no DOM selection, so the host's 'at the selection' actions use it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * build: rebuild the committed platform dist for the settle focus rule Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * fix(notes): make what is typed into an empty note its plain content In a host's note editor (caller protected from typing), a keystroke typed into `\f + \f*` landed inside the closing glyph's bytes (`x\f*`): shown, never saved. EmptyNoteCaretGuardPlugin gives an empty expanded note's content slot a transient caret host, so what is typed becomes the note's own content (`\f + x\f*`, no run marker added). Not applied where the caller is plain editable text, whose end is still the caller's. - transientCaretHost reuses only a bare placeholder at the boundary (any text node - a closing glyph included - used to count as a host there), and releases its CURSOR_CHANGE_TAG after a selection-only repair, which otherwise made the next keystroke read as a caret move and skip onUsjChange. - $emptyNoteContentSlot / $isNoteContentText share the note-content rule with $selectNoteTextOffset. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * build: rebuild the committed platform dist for the empty-note caret guard Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/f7a1ea20-7d76-48e3-ac64-6767e5644b5a * fix(editor): release a scrRef placement's caret tag; tighten the unfocused-update paths - A scrRef-driven caret placement no longer leaves CURSOR_CHANGE_TAG pending for the next commit, which dropped a footnote inserted right after a navigation from onUsjChange. The release is armed only when the caret moved. - releaseTagsAfterNextCommit returns its unregister, and the discrete EditorRef updates disarm it when they commit nothing. - clearStaleDomSelection leaves a DOM selection that matches Lexical's. - selectAfterNote while unfocused dispatches SELECTION_CHANGE_COMMAND, so onScrRefChange reports the note's verse too. - isFocused() uses the same focus check as the rest of EditorRef, so a focused caller button inside the editor counts. - EmptyNoteCaretGuardPlugin moved to its alphabetical slot. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * fix(notes): select the end of a run that holds a nested span; the context menu claims its Escape $applyUpdate materializes a nested span's markers inside the run, so the run's first closing glyph need not be its own: selectNote now accepts only a closer that is the span's last child, and no longer lands the caret before or inside the nested span. The right-click menu now preventDefaults the Escape that closes it, so a host's editor-level Escape can skip it. CHANGELOG covers these and the previous commit. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * build: rebuild the committed platform dist for the caret-tag and note-selection fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * fix(notes): release the caret guards' cursor-change tag after a correction The note-shell guard and the trailing-note guard tag their correction CURSOR_CHANGE_TAG. A correction that only moves the caret commits no node change, so Lexical keeps the tag pending and it rode onto the next keystroke, which DeltaOnChangePlugin then skipped as a caret move: the character showed but never reached onUsjChange. Both now release the tag after their commit, as transientCaretHost already does. Each test types straight after the correction and fails without its release. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * fix(collab): keep a nested span that opens a run when applying a note $applyUpdate built a nested span from a run's first op with the nested span's glyphs beside it in the outer run instead of inside it. The marker-edit engine re-read those bytes as the outer run's own and the nested span was gone, so a note loaded into the footnote popover or pane row as `\ft \+nd LORD\+nd* said` saved back as `\ft LORD said` on any edit. It now builds the canonical shape the USJ adaptor and the mid-run merge branch already build. Text continuing a closed run is inserted before the run's closing glyph rather than after it. Round-trip tests cover a run opening with, holding, and consisting of a nested span. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * fix(notes): typing after an editable caller is note content, not part of the caller An expanded note's editable caller text node is dropped on export only when it is byte-exact, so text typed past the caller's trailing separator exported the whole node, caller included, as content (`\f + + x\ft a\f*`). $noteCallerTextTransform now splits what follows the separator into its own content node in the same commit, the caret following it, so every onUsjChange between keystrokes is already correct. Both nodes are marked unmergeable, or Lexical's simple-text normalization re-merges them and the transform loops. A second space typed after the caller is kept as content rather than collapsed away. Also: the span-first caret test now asserts the saved text, which the previous commit made loadable; CHANGELOG entries for this round. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * build: rebuild the committed platform dist for the nested-span, caller-typing, and caret-guard fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/060fba48-2dc4-4718-9172-4a835abd6dc0 * fix(notes): keep text written directly in a note when applying it to collapsed notes NoteNodePlugin's transforms reset every plain text child of a collapsed note to the NBSP spacer, so a note editor's apply lost text written directly in the note (\f + x\ft a\f*, \f + x\f*). The apply still replaced the note node, so the host's session key stopped resolving and every later apply from the footnotes pane row editor was dropped until it was reopened. Only tagged spacers, and text the caret is typing into, are reset now; other text gets a spacer inserted after it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(notes): narrow a selection out of a protected note shell A range reaching into the \f + shell (a double-click on the caller, a drag from the shell into the content, select-all) was grown to take in the whole shell, so typing or deleting over it removed the shell and unwrapped the note. Ranges are now narrowed to the note's content instead, and one wholly inside the shell collapses to the start of the content. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(caret): keep a visible caret past a note that ends an unclosed char span A collapsed note that is the last child of an unclosed char span (\wj with no \wj*) ends its line just as a paragraph-level trailing note does, but the trailing-note guard only recognized a note directly in its block: a click past the end of such a line lost the caret and the editor's focus, and ArrowRight into it left an invisible caret in the note's hidden closer. The guard now walks up through inline ancestors that render nothing after the note, and the arrow landing past such a note stays an element point. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(marker-edit): settle an undeclared char marker back to text when its glyph is edited A char span whose marker the stylesheet does not declare was always kept whole through a Tier 2 rebuild, so deleting the backslash of \df never reached the tokenizer: the span survived and the damaged glyph was healed back (\+df). An undeclared span is now kept whole only while its own glyphs still spell it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * feat(notes): address a note's \cat category and read the caret back in note terms - selectNoteTextOffset takes an optional field: "category" to put the caret in the note's \cat value, so a click in a footnotes pane row's category lands there in the row editor. - getNoteCaret reports where the caret is within an expanded note in the same terms, so a host can hand that position to its own note editor. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(notes): report only nodes a local edit actually inserted An edit inside an existing note diffs as that note replaced by its new self, so onUsjChange reported the note as inserted and hosts opened their new-note editor on the note the user was typing in (the footnotes pane row editor, at the end of the note). The key is reported only when the previous editor state did not have it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * build: rebuild the committed platform dist for the note caret, shell, and settle fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * docs(invariants): a note shell narrows ranges; text directly in a note is content Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * docs(changelog): note caret APIs and the round of note-editing fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * refactor(notes): drop getNoteCaret; pin an unclosed note staying unclosed through an apply The host no longer moves a caret from an unclosed note in the text into its own note editor (an unclosed note is edited in place, as in Paratext 9), so nothing reads the caret back in note terms any more. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * build: rebuild the committed platform dist without getNoteCaret Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(notes): narrow a range out of a protected shell when it is typed or deleted over During a drag the browser owns the DOM selection until the edit, and Lexical re-reads the range from it for the edit, so the narrowing done on the selection change was gone by then: typing over a drag across \f + removed it. The edit commands now narrow the range first; one holding only the shell deletes nothing. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(notes): an unclosed note's caller can be deleted, as in Paratext 9 Deleting the caller of an unclosed note in Standard view reverted: the caller pattern needed a non-empty word, the whitespace display and the caller transform then fought over the empty slot, and the reverse adaptor let the empty slot's spaces leak into the content. The caller slot is now found by position, an empty caller is kept (""), and the text shows \f \fr ... with both separators, which ParatextData writes as \f \fr ... - the same file Paratext 9 writes. $createWholeNote's caller-slot change is in the next commit, alongside the caret mapping in the same file. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(marker-edit): typing a note's own closer closes an unclosed note; keep the caret on a typed unknown marker - A \f* typed into an unclosed note came back from the note-scoped rebuild as an unmatched marker inside the note. It now closes the note there: the note loses closed="false" (collapsing to its caller in Standard view), and whatever followed the closer moves after the note in the paragraph. - After a rebuild the caret is restored by byte position, and a freshly built undeclared-marker span (\df) counted as a one-byte placeholder while the position had been measured over its typed bytes. The caret landed in the next closing glyph, so every later keystroke edited the glyph and never reached the note. Spans the rebuild did not preserve are counted byte by byte. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * feat(notes): place a note caret inside a marker glyph; editable expanded notes always build a caller slot - selectNoteTextOffset's third argument is now an options object: field "category" as before, plus a glyph locator (which marker at a content offset, and how far into its text), so a click on \fr, \ft*, \cat or \cat* in a host's rendering of a note lands at that character in the editor. - $createWholeNote builds the caller slot for an empty caller too in an editable expanded note, as the load path does, so an apply onto a note whose caller was deleted keeps its separators. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * docs(changelog): unclosed-note caller and closer, unknown-marker caret, shell drag Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * build: rebuild the committed platform dist for the unclosed-note and caret fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(notes): a backward delete at a protected shell's edge no longer removes the caller After a drag or a click in the shell the caret rests at the shell's trailing edge, and Backspace, a word delete, or a line delete from there took the whole caller token. Deletes that would reach into the shell are refused or stopped at its edge. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(marker-edit): forward Delete through an opening glyph goes one character at a time The press that removed an opening glyph's last character also removed its separator, and the caret jumped to the end of the span: the empty-char placeholder cleanup read the separator NBSP as the placeholder and called selectEnd. That press now removes just the character, turns the separator into the text's own space and keeps the caret where it was. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * fix(marker-edit): an undeclared marker typed in a note stays a sibling of the run it ends With a \cat run in the note a note-scoped rebuild ran after the commit, and the undeclared span, kept whole as a sentinel, was spliced back inside the still- open \ft (showing as \+df); the caret restore then landed on \cat, so later typing never reached the note. Inside a note the tokenizer reads an undeclared marker as a char span, so there it is re-tokenized like any other. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * feat(notes): getOpsAfterNote, and replaceEmbedUpdate keeps inserts after the note A note editor that closes its note mid-note (a typed \f*) holds the text that followed the closer after the note. getOpsAfterNote reads it, and replaceEmbedUpdate now deletes the old embed before any further inserts so that text lands after the new note in the host editor instead of being deleted with the old one. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * build: rebuild the committed platform dist for the delete, unknown-marker, and note-close fixes Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A2bfdNETynYMPVnLcrc1sm * feat(notes): takeOpsAfterNote; closing a note by typing its closer is one undo step - EditorRef.takeOpsAfterNote removes what follows a note in its paragraph and returns its ops, joined to the undo step of the edit that left the text there. A note editor that took the text a mid-note \f* moved out then gets one undo that opens the note again with the text inside, instead of an undo that puts the text back after the note (where the host took it again, on every press). - The close of an unclosed note at a typed closer merges into the undo step the closer was typed in, so one undo takes the whole \f* away, not just its '*'. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): protect a note editor's closing glyph as the opening shell is In a note editor (shell not editable) the note's closer could be deleted: a caret after \f* or at the row's end stayed there, Backspace from there removed the closer, forward Delete ran straight into it, and typing over a range inside it prepended to it. Range narrowing was the only closer protection. - A caret in, on, or past the closer (or past the whole note at the row's end) moves to the end of the note's content, as a text point: an element point at the closer's index resolves to the closer's own start. - Backspace or Delete there is claimed and moves the caret instead; a forward delete with nothing left before the closer is refused, and a word or line delete stops at the closer, mirroring the opener's backward rule. - A range narrowed off the closer collapses to that same text point. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * build: rebuild the committed platform dist for takeOpsAfterNote and the closer guard Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): undo of a closer typed into an unclosed note keeps the text typed before it In the app the marker palette commits a typed \f* and the note's close in one update. The close carried a history-merge tag, so that update joined the previous undo step: one undo took the close away together with the text typed just before it, and that text was lost. The close now forms its own undo step (a note editor's takeOpsAfterNote still joins it). Closing the note also keeps the same note node rather than replacing it. The replacement was reported to hosts as an inserted note, so Platform.Bible opened its new-note editor on the note just closed and moved focus there. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * build: rebuild the committed platform dist for the note-close undo fix Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): review round — note-shell deletes, caret after a closed note, reentrant applies - A protected note shell (isNoteShellEditable: false): a forward Delete with the caret just before the note is refused instead of removing the opener and unwrapping the note; a forward Delete at the shell's trailing edge reaches the content after the caller; a forward line delete over wrapped content is not clamped to the closer when the closer is on another line. - Typing a note's own closer in a view that shows notes expanded leaves the caret after the note (only a host's note editor keeps it in the note). - selectAfterNote on a note ending an unclosed char span places an element point after the note instead of descending into the note ($selectElementPoint moves into note.utils and is shared with arrow navigation). - applyOps reports from the update's onUpdate, so takeOpsAfterNote called from onUsjChange shows in getUsj() and reports its own onUsjChange. - getNoteOps/getOpsAfterNote/takeOpsAfterNote read with readLatest, safe from a callback during an update. - $findFirstAncestorNoteNode replaces three hand-written note lookups; test fixtures follow the nested-chain style; TSDoc and CHANGELOG fixes. Rebuilt the committed dist. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): collapse spaces between a note's caller and its content on save Standard view collapses space runs when it saves, but a run split across the caller and the note's content (a space typed after an expanded note's caller, or `\f + text` in the file) was saved as leading note content. The reverse adaptor now drops leading plain spaces from the note's first content string in Standard view, as Paratext 9 reformats `\f + text` to `\f + text`. A note with a category keeps them (they follow `\cat*`), and an NBSP stays. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): keep arrow navigation's caret announcement; report a close inside an unclosed span $selectElementPoint again announces every move past a collapsed note, as arrow navigation relies on for its caret host. $selectAfterNote keeps a paragraph's own select, and a caller that also changes the document (closing a note) places the caret without the announcement: the guard's repair tags its whole commit as a caret move, which kept a note closed at the end of an unclosed \wj out of onUsjChange and getUsj(). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * fix(notes): a range ending inside a collapsed note takes the whole note Selecting to the end of the document from a paragraph a footnote ends puts the range's end at the start of the note's hidden content, since the browser has no position inside it. Copy then carried `\f + ` without the note's content, and cut or typing over it left half a note. The trailing-note guard now moves a range end that is inside a collapsed note to the near side of the note. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NDp2WYL6HtB3S7MSRqMheJ * fix(notes): End and Ctrl+End past a trailing collapsed note leave the caret there In a block that a collapsed note ends there is no caret position past the note, and the browser answers a jump to the end (End, Ctrl+End, Cmd+Down) by selecting the note. The next paste, typing or deletion then replaced it. The trailing-note guard now turns that selection into a caret past the note when it arrives right after such a press. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NDp2WYL6HtB3S7MSRqMheJ * test(editor): stub Range rects for the focused applyUpdate case After main's caret changes the focused case leaves a collapsed caret, and Lexical's scroll-into-view then measures it through a Range, which jsdom does not implement. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * build: rebuild the committed dist after merging main Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(notes): text typed right after a note's closing glyph moves after the note A browser reading back a caret at the end of a line a note ends resolves it to the end of the note's closing glyph, so the next keystroke became `\f*Z`: invisible in a collapsed note and dropped from the USJ in every view. Tier 1 already splits text typed after a char span's own closer out of the span; the same split now covers a note's own closer. That covers clicking at the end of such a line in Unformatted view and typing after closing a note that ends an unclosed char span (lyonsil round 13 follow-ups #1 and #5). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * build: rebuild the committed dist Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Seeds this repo as the paranext organization's source of truth for the editor packages, and documents what that means for everyone who works here or consumes it.
Part of PT-4500.
What this does
Ownership and provenance. Adds a
Where this repository livessection: this is a standalone copy ofeten-tech-foundation/scripture-editorscarrying full history, MIT license, and attribution — deliberately not a GitHub fork, because while a repo is a fork GitHub always defaults new PRs to the parent and offers no setting to change that. Adds a SIL Global / United Bible Societies copyright line alongside ETEN Tech Foundation's; the license stays MIT.Relationship to paranext-core. Documents that paranext-core does not install these from npm — its
preinstallbuilds them from source and stages them, and itspackage.jsonfiles reference the staged folders withfile:specifiers. The consequence worth knowing: this repo'spackage.jsonfiles are authoritative for its own dependencies, so adding or bumping one here flows into paranext-core with nothing to restate on the consuming side.The
platform-yalcbranch. Explains why it still exists — the name is historical (paranext-core no longer uses yalc), but its coordination role is real: a breaking change lands onmainfirst andplatform-yalcmoves forward only once the consuming side is ready.The eten-tech-foundation remote. How to add it (named
eten-tech-foundation, notupstream— we don't track it), pull from it, and contribute back. We may never use it, but the option is deliberately kept open.Transferring work.
docs/transferring-work-from-eten-tech-foundation.md— this repo was seeded with a curated ref set (main,platform-yalc,release-prep, and all 80 release tags), so feature branches were left behind. The guide covers moving branches, tags, and open PRs across, plus re-pointing an existing clone non-destructively.Release process
Replaces the npm-publishing machinery with a process modeled on paranext-core's. Consumers pin a revision of this repository, not a published version, so a release is a repository tag and one tag pins both packages. Tags are
v<platform-editor version>.scripts/bump-versions.ts+bump-versionsworkflow and composite action — sets both package versions on abump-versions-<version>branch. Tested locally; it moves both manifests and correctly leaves theworkspace:specifier alone.publishworkflow — verifies the requested version matchespackages/platform/package.jsonbefore tagging (a tag disagreeing with the manifest would pin consumers to a build claiming a different version), creates the release, and can open the follow-up bump branch.test-publish.ymlbecomestest.yml, a pure CI workflow.Nx Cloud references are dropped — no account for this org, and the caching doesn't earn standing one up. It was already commented out in the test workflow ("credits exhausted").
Notes for review
@eten-tech-foundation/*; renaming was explicitly out of scope.packages/scriberemoval is a separate PR so the diff against upstream stays easy to reason about.v<platform-editor version>at the repo level rather than keeping per-packageplatform_v*/utilities_v*tags. Since consumption pins one repo revision, one tag pinning both packages seemed the honest unit, but it's a judgment call.bump-versionsandpublishareworkflow_dispatch-only and want a real dispatch before anyone relies on them.🤖 Generated with Claude Code
https://claude.ai/code/session_01VCWPCf35QD5sTkFghsTfUX
This change is
Merge order
This is step 1 of eleven PRs that cannot all be green at once.
Immediately after this merges, move
platform-yalconto the newmain(
npm run move-platform-yalc) — it currently carries no committeddist/, and until it does,paranext-core's staging falls back to a pnpm/nx build that no consumer runner can perform.
In that window
verify-platform-yalc.ymlfails by design: it readsdev-packages.jsonfromparanext-core's
main, which still predates staged consumption, so there is no lockfile contract tocompare against.
npm run move-platform-yalc -- --skip-verifyis the intended way through, and thisis the one window it is for. Then merge
paranext-core#2745, then the nine consumer
PRs. Full sequence is in core#2745.