Skip to content

Adopt this repository into the paranext organization - #1

Merged
tjcouch-sil merged 31 commits into
mainfrom
adopt-into-paranext-org
Sep 11, 2026
Merged

tjcouch-sil merged 31 commits into
mainfrom
adopt-into-paranext-org

Conversation

@tjcouch-sil

@tjcouch-sil tjcouch-sil commented Aug 31, 2026 •

Copy link
Copy Markdown
Member

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 lives section: this is a standalone copy of eten-tech-foundation/scripture-editors carrying 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 preinstall builds them from source and stages them, and its package.json files reference the staged folders with file: specifiers. The consequence worth knowing: this repo's package.json files 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-yalc branch. 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 on main first and platform-yalc moves forward only once the consuming side is ready.

The eten-tech-foundation remote. How to add it (named eten-tech-foundation, not upstream — 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-versions workflow and composite action — sets both package versions on a bump-versions-<version> branch. Tested locally; it moves both manifests and correctly leaves the workspace: specifier alone.
  • publish workflow — verifies the requested version matches packages/platform/package.json before 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.
  • Removes the scribe publish workflow, the tag-triggered npm publish steps, and the auto-bump-after-publish job. test-publish.yml becomes test.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

  • Nothing here changes the editor's architecture, public API, or package names. Package names stay @eten-tech-foundation/*; renaming was explicitly out of scope.
  • packages/scribe removal is a separate PR so the diff against upstream stays easy to reason about.
  • The release process is the piece I'd most like a second opinion on — in particular the choice to tag v<platform-editor version> at the repo level rather than keeping per-package platform_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.
  • The workflows are not exercised by this PR. bump-versions and publish are workflow_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 Reviewable

Merge order

This is step 1 of eleven PRs that cannot all be green at once.

Immediately after this merges, move platform-yalc onto the new main
(npm run move-platform-yalc) — it currently carries no committed dist/, 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.yml fails by design: it reads dev-packages.json from
paranext-core's main, which still predates staged consumption, so there is no lockfile contract to
compare against. npm run move-platform-yalc -- --skip-verify is the intended way through, and this
is the one window it is for. Then merge
paranext-core#2745, then the nine consumer
PRs. Full sequence is in core#2745.

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.
@tjcouch-sil
tjcouch-sil force-pushed the adopt-into-paranext-org branch from ec221be to 75adc47 Compare September 1, 2026 22:27
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.
@tjcouch-sil
tjcouch-sil force-pushed the adopt-into-paranext-org branch 2 times, most recently from 75adc47 to b3b88d4 Compare September 2, 2026 14:47
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.
@tjcouch-sil

Copy link
Copy Markdown
Member Author

Added: the built dist/ is now committed (closes #4, brought into this round rather than deferred).

packages/platform/dist and packages/utilities/dist are tracked, so paranext-core consumes these packages by copying rather than building — no pnpm, no nx, no build during its npm install. Measured on a checkout that has the committed dist: ~7 seconds instead of several minutes, and the whole Volta/pnpm class of install failures leaves the consumer path entirely.

Guarding the obvious risk (a stale dist is invisible in review):

  • scripts/verify-committed-dist.mjs + a CI step that rebuilds and fails on any drift.
  • Determinism verified before relying on it — rebuilt and compared hashes; every published artifact is byte-identical.
  • The one non-deterministic file was dist/*.tsbuildinfo, which turned out to be TypeScript's incremental cache being packed into consumers as though it were a shipped artifact. Now excluded from both git and files.
  • README documents the rebuild-and-commit obligation.

Two things reviewers should know:

  1. nx caches dist as a target output, so a cache hit restores nx's copy over the committed one and can delete files the cache predates — I hit exactly that (17 spurious deletions). paranext-core's staging builds with --skip-nx-cache. If you see unexplained dist deletions locally, git checkout -- packages/*/dist.
  2. Until this merges and platform-yalc rebases past it, core still builds via its fallback path — verified working, so there is no window where core breaks.

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.
tjcouch-sil and others added 10 commits September 3, 2026 11:15
`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 rolfheij-sil left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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:

  1. Tag scheme — keep yours. One repo-level v<platform-editor version> is the honest unit because consumers (core's dev-packages.json, studio's productInfo.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 justified platform_v*/utilities_v* is gone. One gap: the tag doesn't disclose the utilities version — have publish.yml put it in the release body (read packages/utilities/package.json in the workflow).
  2. move-platform-yalc locally hits the anonymous rate limit. verify-consumer-lockfile-sync.mjs sizes its 7-day window against the 60 req/h unauthenticated budget (its own comment says ~51 PRs), but npm run move-platform-yalc is the documented local command and GITHUB_TOKEN isn't set outside Actions. A 403 currently surfaces as a bare GET … -> 403 Forbidden (fetchJson, L52–56). Suggest catching 403 and telling the caller to export GITHUB_TOKEN=$(gh auth token), and saying so in the README section.
  3. #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) and pnpm-lock.yaml. Whichever merges second needs a manual resolve + lock regeneration — not a rebase-clean situation.
  4. Manual npm-publish path is still fully wired: .npmrc (_authToken=${NODE_AUTH_TOKEN}, always-auth), both packages' publishConfig + prepublishOnly/postpublish, and scripts/prepare-publish.ts. CI no longer calls it, but anyone with scope rights could still pnpm publish by hand. Given the "no npm publishing" decision, either remove it or note in the README that it's deliberately kept.
  5. README "Releasing" steps 2/4 say "merge the bump-versions-<version> branch" — main is protected, so that's "open a PR from it"; the old flow auto-opened one, the new composite action only pushes the branch.
  6. Repo hygiene vs the ticket (not this PR's job, but unowned today): no CODEOWNERS (named in PT-4500 item 3), delete_branch_on_merge is 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 _nxCloudAccessToken you remove from nx.json has been in upstream's public history for a long time — worth a quick "is it inert?" with whoever owns that Nx Cloud account.
  7. The workflows are unexercised, as you say — a single workflow_dispatch of bump-versions and publish on 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
@tjcouch-sil

Copy link
Copy Markdown
Member Author

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 0d456a84.

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 platform-yalc had no mention of GITHUB_TOKEN at all. It now says the check spends tens of requests against the 60-an-hour anonymous budget, that Actions sets the token but a local run does not, and gives the one line.

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 x-ratelimit-remaining, and a secondary limit sends retry-after instead. My first version matched only 403-with-remaining-zero, so it would have missed the 429 form of both and every secondary limit. It also treated any unauthenticated 403 as a rate limit, which would confidently mislabel a genuine permissions failure — that case now gets the same advice (a token helps either way) under a hedged description rather than a wrong one.

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.

tjcouch-sil and others added 6 commits September 10, 2026 13:43
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
@tjcouch-sil
tjcouch-sil merged commit bb0778b into main Sep 11, 2026
5 checks passed
@irahopkinson
irahopkinson deleted the adopt-into-paranext-org branch September 22, 2026 19:54
tjcouch-sil added a commit that referenced this pull request Oct 12, 2026
… 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>
tjcouch-sil added a commit that referenced this pull request Oct 12, 2026
…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>
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.

2 participants