Choose or Create Lexicon

[alex-rawlings-yyc]

• Users with no existing lexicon have little or no friction to create and start with a blank one
• Users that have Paratext 9 lexicon get a choice to create from Paratext 9 data
• Users have an option to sign into Lexbox to choose a lexicon
• Users have an option to open a local fieldworks lexicon
• [Future] Users can import a lexicon from a known file type (LIFT, Fieldworks backup?, )

[imnasnainaec]

Full feature depends on

• Add Lexbox login to the Platform.Bible lexicon extension languageforge-lexbox#2426
• [PB Extension] Create FW project languageforge-lexbox#2394
• [P.B ext] Enable selecting a remote project languageforge-lexbox#2461

[imnasnainaec]

To clarify:

• Will the in-interlinearizer lexicon be in the interlinear project envelop or being saved to file?
• Will we implement it with Harmony? How will the project interact with send/receive that's now enabled in PT10? (Investigate how interlinear data interacts with Send/Receive #256)

[imnasnainaec]

Plan for this issue, with the decisions it forced recorded so they don't have to be re-derived. No code yet.

Where the four bullets stand today

Bullet	Status
Create and start with a blank lexicon	Exists — lexicon.createLexicon and the SelectLexicon create form (sillsdev/languageforge-lexbox#2394)
Create from Paratext 9 data	Not built anywhere. We hold the PT9 half (src/converters/pt9/lexiconResolver.ts, the Lexicon.xml parser); the Lexicon extension holds none of it
Sign into Lexbox to choose a lexicon	Sign-in exists (sillsdev/languageforge-lexbox#2426); choosing a remote lexicon is sillsdev/languageforge-lexbox#2461, open
Open a local FieldWorks lexicon	Exists — lexicon.lexicons over local FwData projects

So most of this issue is a delegate-vs-build call rather than a build-it-all one.

The rule this is built on

One FW Lite lexicon is linked to a Paratext 10 project. Exactly one, and changing it is possible but deliberately hard. Everything below follows from that, including the decision not to scope a lexicon per interlinearizer project.

The constraint that shapes the rest

IEntryService takes a Paratext projectId and resolves the lexicon from that project's lexicon.lexiconCode setting (languageforge-lexbox: platform.bible-extension/src/services/entry-service.ts). There is no lexicon-code override on any method, and the parameter is never used as a project id — it is only ever fed to ProjectManager.getLexiconCode. So every call we make would silently resolve through a setting we do not own.

Shape

#44 delivers a provider registry and a chooser over it; FW Lite is the first provider registered behind it. Nothing in the chooser, the stored link, or the analysis model names FW Lite. Tier 1 (#46's open question) later means registering a second provider, not revising this work. That question stays open — nothing here decides it.

Decisions

D1 — The link is a Paratext-project setting of our own: { authority, projectId }, both required.
One link per PT10 project, per the rule above. We contribute it in contributions/projectSettings.json and validate it with papi.projectSettings.registerValidator, both of which this extension already does for seven settings — no new mechanism. projectId holds the FW Lite lexicon code and is not optional: the link is changeable, so a stored link that doesn't name its lexicon is unusable after the first change.
Rejected — reusing lexicon.lexiconCode: it enforces the same cardinality and already has the sticky change behavior we want, but an FW Lite lexicon code cannot name a tier-1 lexicon, so #46's options 2/3 would need a second mechanism. It is also cleared by the Lexicon extension itself when a lexicon stops resolving.
Rejected — storing the link in our own project or draft records: that scopes it per interlinearizer project, which contradicts the rule.

D2 — Dependency on the Lexicon extension: lazy runtime discovery.
No startup acquisition and no subscription. Resolve lexicon.entryService when the chooser opens or a lexicon-backed action fires, using waitForNetworkObject with a short timeout. Absence is a supported state, not an error.
Why not declare it: extensionDependencies is unenforced — nothing reads it, and dependency-ordered activation is an open TODO (paranext-core: src/extension-host/services/extension.service.ts:523), so a one-shot lookup at activation can miss an extension that is installed and simply hasn't activated yet. networkObjects.get returns undefined without blocking when an object is absent (paranext-core: src/shared/services/network-object.service.ts:615-633), so checking is cheap.
Later if needed: an onDidCreateNetworkObject subscription, only for screens that must notice a provider arriving mid-session.

D3 — Ref stamping: one fw-lite authority; projectId carries the lexicon code.
Both backing stores share it. CrdtFwdataProjectSyncService syncs one logical lexicon between FwData and CRDT while preserving entry ids, so there is one id space, not two.
Rejected: separate authorities per backing store. It would split that id space — the same entry would carry different refs depending on which copy resolved it, and a lexicon gaining a CRDT copy would strand every existing ref as foreign, silently degrading working glosses.
Noted: the model already treats a fw-lite ref without a project id as malformed — LexiconRef.projectId is optional only for "an authority whose lexicon is not divided into projects." Whether to tighten that to a required field in the type is a small separate call; the behavior is contractual either way. FwLiteWeb exposes no rename endpoint, so codes look stable; a code change would strand refs the same way a relink does.

D4 — Which lexicons the provider resolves: only the linked one.
A ref naming a different lexicon misses and falls through the render ladder to its stored free-form gloss, which is what the port's resolveSense contract already describes. This is the deliberate consequence of relinking being hard: after a change, previously linked glosses render as their free-form text and the refs survive untouched.
Corollary, and it matters for #227: the provider declares its authority whenever it is available (D2), not whenever it is connected to a lexicon. Otherwise a project with no link reads every ref as foreign rather than as a miss — the same rendered output, but a different fact, and #227's link indicator distinguishes them. Foreignness stays a property of the ref, as #225 intends.

D5 — Creating a blank lexicon: one prefilled step.
"Create a new lexicon" sits alongside the other options with fields prefilled from the project; one confirmation commits it. Creation is once per PT10 project, so it is not a per-draft artifact.
Possible later, both cheap: zero-prompt creation with fully derived defaults — more attractive now that a created lexicon is not per-draft — or deferring the whole chooser to the first create-or-link attempt. Both stay cheap only if two constraints hold now: the first-open offer is dismissible, never a gate, and creation goes through the provider's createLexicon(draft) rather than being wired into the form component.

D6 — Declared capabilities: search: true, create: true, allomorphs: false, msas: false.
MiniLcm has no allomorph record — Entry carries LexemeForm, CitationForm, and one MorphType, and Variants/VariantsOf relate separate entries. Sense.PartOfSpeech exists, but the port defines an MSA as part of speech plus inflection class and stem features, per usage.
Deferred: splitting a partOfSpeech capability out of msas so POS can be surfaced honestly. Worth doing when a POS affordance is actually designed; #227 is gloss display only.

D7 — No change to DraftProject or InterlinearProject, and so no modelVersion bump.
The link lives on the Paratext project, not in our records, so nothing is added to either envelope, nothing needs carrying across Save As, and the model-version question does not arise. Provenance is already in the refs, which name their lexicon (D3).

D8 — A bilateral project uses its source project's link.
sourceProjectId names the text being analyzed and TextAnalysis is the analysis of that text, so the source project's link governs. A target project's own link, if it has one, is not consulted.

Open questions

1. One setting or two. { authority, projectId } as a single JSON-encoded value is atomic — no half-updated link — but every project setting in either extension today is a scalar. Two settings (interlinearizer.lexiconAuthority, interlinearizer.lexiconCode) match precedent and stay human-readable at the cost of atomicity.
2. Whether we mirror the link into lexicon.lexiconCode. The rule says one lexicon per PT10 project, but two settings will now describe that fact and can drift — a user relinking in one extension leaves the other stale. Mirroring on write keeps them agreeing at the price of one extension writing another's setting. Not mirroring keeps ownership clean and accepts drift. Neither is obviously right; it should be chosen rather than defaulted into.
3. Reuse the Lexicon extension's selector UI, or build our own. Its SelectLexicon webview commits to lexicon.lexiconCode, so reuse needs the upstream change below. Building our own chooser needs no upstream UI change at all, since lexicon.lexicons and lexicon.createLexicon both return values without writing any setting.

Work items

1. Provider concept on the port. LexiconProvider alongside LexiconResolver — { authority, displayName, isAvailable(), listLexicons(), createLexicon?(draft), connect(id) }, create optional so a read-only provider is expressible. Note the two lifetimes: availability is session-wide, connection is per-project.
2. Rescope the registry. src/hooks/useLexiconRegistry.ts assembles it once per session — "so its answers never vary by component or by render" — which a per-Paratext-project link contradicts, since more than one project can be open. It becomes scoped to the project in view, and gains listing and runtime connect over today's fixed [nullLexiconResolver] array (src/utils/lexicon-resolvers.ts).
3. The project setting. Contribute and validate it per D1.
4. FW Lite provider. Availability per D2; listing via lexicon.lexicons; creation via lexicon.createLexicon; resolver is the FW Lite adapter: resolve lexicon refs for display #227 adapter over getEntry / getSense / getEntries / addEntry.
5. The chooser, rendering providers rather than FW Lite. Rows are "no lexicon" plus each available provider's lexicons and its create affordance. With one provider it reads as this issue's bullets; a second provider adds rows without touching the chooser.
6. First-open offer, reusing the pattern the PT9 import modal established rather than inventing a second one.

Upstream

Both filed as sillsdev/languageforge-lexbox#2626, one checkbox each. Neither changes anything a user of the Lexicon extension on its own can see.

1. Make IEntryService lexicon-addressed. Required, not optional: we store our own link, and a project-addressed service would resolve through lexicon.lexiconCode instead — so any drift between the two settings would silently send our reads and writes to a different lexicon than the one we recorded. Breaking, and fine: pre-release, and no code outside that extension calls lexicon.entryService.
2. Have the selector report a chosen or created lexicon instead of committing it, as an added mode. Needed only if open question 3 resolves toward reuse.

Out of scope

• Creating a lexicon from Paratext 9 data — needs a target store to write into and a converter; its own issue.
• Remote Lexbox lexicons — [P.B ext] Enable selecting a remote project languageforge-lexbox#2461.
• Which tier 1 is — Allow user to gloss internally and through Lexicon extension #46's open question, deliberately untouched.
• Send/Receive — Investigate how interlinear data interacts with Send/Receive #256.

Related

#46 (the epic and the tier-1 question), #225 and #226 (the port and ref namespacing this builds on), #227 / #228 / #229 (the adapter, linking, and writing that follow), #256 (where analysis data lives).

Housekeeping

The "Current Lexicon gap" notes on EntryRef and SenseRef in src/types/interlinearizer.d.ts say no by-id lookup exists; getEntry and getSense have since landed.

---

Drafted by Claude Opus 5.