PT-4731: Show Biblica license notice on restricted texts

[katherinejensen00]

Code Review Summary

Branch: pt-4731-biblica-texts-special-message

Base: origin/main

Date: 2026-09-24

Review model: Claude Opus 5.5

Files changed: 98. About 1,800 lines are production code; the rest is tests, stories, translations, test fixtures and generated files.

Summary

What users see. Biblica licenses some texts (NIV, NVI and others) as "reference text" resources only: they may not be translated or used as the basis for a new translation. When one of these resources is open, Simple and Power mode now show a dismissible banner with Biblica's wording.

• The banner is clamped to two lines, with Show more.
• "More info" opens a "Copyright for " dialog with Biblica's terms and a biblica.com/permissions link.
• A narrow Text Collection cell shows a small indicator instead.
• The same banner also shows Paratext 9's existing "Notification:" copyrights.

Second feature (the ticket's nice-to-have). These texts are greyed out, with a reason, in the pickers. They can't be chosen as a model text (resource picker, Team Layout) or as the base of a new book (Manage Books "Create based on"). An existing selection is kept, and its banner shows.

How it works. One C# check, BiblicaLicensing.IsRestricted, decides what is restricted. It applies to resources only: the DBL id must be on Matt T's list of 56 texts, or the copyright must say "Biblica, Inc." without "Biblica Open". That check reaches the UI by two paths:

• Banner: a computed, read-only project setting, platformScripture.copyrightNotice.
• Pickers: listModelTextRestrictions, which platform-get-resources stamps onto rows as isRestrictedAsModelText, and ProjectSummary.IsRestrictedAsBase for Manage Books.

Suggested reading order

#	Area	Start here	What it does
1	The rule (C#)	c-sharp/Projects/DigitalBibleLibrary/BiblicaLicensing.cs	IsRestricted: the id list, the copyright rule and the Open-text exemptions. Tests: BiblicaLicensingTests.cs, backed by a survey of 1,819 DBL texts in TestData/.
2	The setting (C#)	c-sharp/Projects/CopyrightNotice.cs, ParatextProjectDataProvider.cs	Builds the none / notification / restrictedLicense value, which is read-only. The TS type is CopyrightNotice in platform-scripture.d.ts.
3	Banner UI	extensions/src/platform-scripture-editor/src/copyright-notice/	project-copyright-notice.component.tsx reads the setting and handles dismissal. It renders copyright-notice-banner, copyright-details-dialog and, in narrow cells, copyright-notice-indicator.
4	Banner hosts	platform-scripture-editor.web-view.tsx, model-text-panel.*, resource-text-panel.*, scripture-text-grid/resource-cell*	Each places the banner. The grid also stops clicks and keys in the dialog from reaching the cell (chapter-context-escape.utils.ts).
5	Picker restriction	ModelTextRestrictions.cs → platform-get-resources/src/model-text-restrictions.utils.ts → src/renderer/components/dialogs/restricted-model-text.utils.ts → resource-picker.dialog.tsx, team-layout.*	Fetches the restricted ids, stamps rows, and disables them through ResourcePickerDialog's new getDisabledReason.
6	Manage Books	c-sharp/ManageBooks/ProjectSummary.cs → manage-books-dialog.component.tsx → ProjectSelector	IsRestrictedAsBase becomes a disabledReason. ProjectSelector disabled rows can now show their tooltip.

Safe to skim:

• Generated: lib/*/dist/, lib/papi-dts/papi.d.ts.
• Translations: the 33 locales in localizedStrings.json.
• Test fixtures: the TestData/*.json files.
• Housekeeping: the ADR entry adr-biblica-license-notice-computed-setting.

Decisions worth a second look

• Paratext 9 parity. A "Notification:" copyright shows its banner on any project. The Biblica notice shows on resources only, since an editable project is the user's own translation. A dismissed banner comes back when the pane switches to another text and back.
• Enforcement is UI only. Only the pickers enforce the restriction. An existing model or base selection isn't cleared.
• No e2e test. A DBL resource can't exist in an isolated e2e profile. Unit and component tests cover the behaviour.
• Translations are AI-generated and not native-reviewed. All 33 locales were translated this way. "Outside of Paratext" is Biblica's own wording, left verbatim.
• Known gap, a follow-up. In Manage Books, cmdk skips disabled rows with the keyboard, so the reason there shows on hover only.

How to try it

• Storybook: Bundled Extensions/platform-scripture-editor/CopyrightNoticeBanner has 7 stories, including the dialog, a right-to-left name and a "Notification:" text.
• In the app: install a Biblica resource such as NIV11, then:
  1. Open it in the editor or as a model text, and check that the banner appears.
  2. Open Team Layout's model-text picker or Manage Books "Create based on", and check that it is greyed out with a reason.

Full review notes: API changes, findings, interview and quality checks

API Changes

• lib/platform-bible-utils (resources.model.ts): DblResourceData gains an optional isRestrictedAsModelText?: boolean field.
• lib/platform-bible-react (experimental ResourcePickerDialog): ResourcePickerDialogProps gains an optional getDisabledReason?: (resource: DblResourceData) => string | undefined. When it returns a reason for a row in the "Installed" or "Available to Download" section, that row is dimmed, shows a lock icon and a tooltip, and cannot be picked.
• lib/platform-bible-react (experimental ProjectSelector): no signature change. Behavior changes:
  • Disabled rows now receive pointer events (tw:data-[disabled=true]:pointer-events-auto), so their disabledReason tooltip can open.
  • disabledReason is exposed to screen readers through aria-describedby.
  • The JSDoc on ProjectSelectorProject.disabledReason was updated to match.
  • Updated during review: a disabled row no longer shows the bound-but-closed "Open" button, and the isBoundButClosed JSDoc says so.
• papi.d.ts (renderer/components/dialogs/dialog-definition.model, reached through the dialog types): ResourcePickerDialogOptions gains an optional disableRestrictedModelTexts?: boolean. It matches the source in src/renderer/components/dialogs/dialog-definition.model.ts and looks regenerated, not hand-edited.
• extensions/src/platform-scripture/src/types/platform-scripture.d.ts:
  • New exported type CopyrightNotice, a union over kind: none, notification and restrictedLicense.
  • CopyrightNotice is added to the papi-shared-types import.
  • New project setting 'platformScripture.copyrightNotice': CopyrightNotice in ProjectSettingTypes. It is computed and read-only; C# throws InvalidOperationException on a write.
• extensions/src/platform-get-resources/src/types/platform-get-resources.d.ts:
  • New exported type ModelTextRestrictions ({ dblIds: string[]; projectIds: string[] }).
  • New method listModelTextRestrictions(): Promise<ModelTextRestrictions> on IDblResourcesProvider.
  • getCachedResources and getLocalNonDblResources: docs now say each row carries isRestrictedAsModelText, and that a read can wait up to 2 seconds for the first restrictions fetch.
• New localized core key %restrictedModelOrBaseText_disabledReason% (en, es).

Findings

Critical — Must address before merge

None.

Important — Should address before merge

• The CopyrightNotice and platformScripture.copyrightNotice TSDoc said a non-resource project always gets none, but a "Notification:" copyright shows on any project, as in Paratext 9. (fixed during review: both docs now say restrictedLicense applies only to resources, notification to any project whose copyright starts with "Notification:", and otherwise none.)
• "More info…" had an ellipsis, against the Ellipses guideline, because the dialog it opens only shows information. It also clashed with the existing "More info" labels in the same panels. (fixed during review: removed the ellipsis in all 33 locales, and updated the comments, tests and stories to match.)
• The picker tooltip, "This text is disabled from being selected because of licensing terms which prohibit its use as a model or base for a new translation.", is one 25-word sentence, longer than the Tooltips guideline allows. (Author kept it: this is Ian's wording from the ticket.)
• The ProjectSelector disabled-reason line used tw:text-muted-foreground on the tooltip's inverted bg-foreground: about 4.0:1 contrast in light theme and 2.5:1 in dark, below AA. This branch is the first to show text in that line. (fixed during review: dropped tw:text-muted-foreground so the reason inherits the tooltip's own foreground; italics kept; pbr rebuilt.)

Author response: the author fixed three of the four during the interview and kept Ian's tooltip wording on purpose.

Minor — Consider

• M1: BiblicaLicensing.IsOnRestrictedList was public, and its doc described picker callers that don't exist. (fixed during review: made internal and reworded the doc; the tests reach it through InternalsVisibleTo.)
• M2: The banner's messageFormatOf duplicated the choice of string key per notice kind in formatCopyrightNoticeMessage. (fixed during review: one exported getCopyrightNoticeMessageFormat helper is used by both. A deliberate break of the re-measure dependency makes its test fail.)
• M3: The key %resourcePicker_restrictedModelText_tooltip% was also used in Manage Books, which is not a resource picker, and it is a screen-reader description as well as a tooltip. (fixed during review: renamed to %restrictedModelOrBaseText_disabledReason% in en and es and at every call site. The constant was renamed to match. A repo-wide grep for the old key is empty.)
• M3 (other part): the flag has three names, isRestrictedAsModelText, isRestrictedAsBase and disableRestrictedModelTexts. (Author kept them: each names the role in its own context, a resource row "as a model text" and a project "as a base". Unifying them would mean renaming across C# and TypeScript for little gain.)
• M4: The ResourcePickerDialog WithDisabledRows story disabled ESV and NLT, which aren't Biblica texts, with a hardcoded copy of the Biblica reason. (fixed during review: it now uses the sample reason "Not available for this translation", documented as consumer-supplied.)
• M5: In the copyright-notice folder, BIBLICA_PERMISSIONS_URL lived in the message utils rather than the folder's const file, and the folder mixed .util and .utils file names. (fixed during review: moved the URL to copyright-notice.const.ts, and renamed open-in-browser.util.ts to open-in-browser.utils.ts with git mv.)
• M6: In ProjectRowView, hasDisabledReason repeated a term of hasExtraTooltipContent. (fixed during review: hasDisabledReason is declared first and reused.)
• M7: createModelTextRestrictionsCache used this, so destructuring sync or getWithin would break. (fixed during review: they are now closure-local functions. A new test destructures and calls them; it failed before the change.)
• M8: Enhanced Resources already has its own copyright ribbon and dialog, so this is a second, parallel copyright UI. (Author: for information only. Consolidating would mean moving both into platform-bible-react, which is out of scope; it's a follow-up if a third surface appears.)
• M9: The pickers treat restricted texts differently. The resource picker shows a lock icon, the row is reachable by keyboard and the tooltip opens on focus. Manage Books' "Based on" ProjectSelector row has no icon and a hover-only tooltip, and cmdk skips disabled items with the keyboard. (Author: fixing it means changing how the shared ProjectSelector handles disabled rows for every consumer. Follow-up.)
• M10: The narrow-cell indicator's tooltip shows the full banner, about 50 words. (Author kept it: in a narrow Text Collection cell the tooltip is the only place the banner wording appears. The dialog shows Biblica's terms, a different text, so shortening it would drop part of the required notice.)
• M11: Once a pane's banner is dismissed, the only way back to it is to switch texts. (Author: deliberate Paratext 9 parity. Switching to another text and back shows the banner again. Adding a "see it again" control would invent a requirement.)
• M12: ResourceRowCells and DisabledResourceRow used physical-direction classes. (fixed during review: switched to pe-*, ps-* and text-end.)
• M13: The details text says "Outside of Paratext" rather than a product name from the Product Names guideline. (fixed during review: it is Biblica's own required wording. A comment where the key is used says not to reword it without Biblica's agreement, and it is noted here.)
• M14: No story opened the details dialog for a "Notification:" text, the one-paragraph-per-line case. (fixed during review: added a NotificationDetailsOpen story.)
• M15: The platform-get-resources main.ts wiring was untested, both the "resync when a flag changed" decision and the 2-second wait-then-stamp. (fixed during review: extracted into syncModelTextRestrictionsAfterFlagSync, applyModelTextRestrictionsWithin and applyModelTextRestrictionsToCatalogWithin in model-text-restrictions.utils.ts, with 7 new tests, each of which fails when its code is deliberately broken. main.ts now just calls them.)
• M16: The branch also adds a second feature, disabling restricted texts in the model and base pickers, with new public API. (addressed in this description: see the Overview and API Changes.)
• M17: getCachedResources and getLocalNonDblResources can wait up to 2 seconds for the first restrictions fetch, even for callers that don't read the flag. (Author kept it: the wait only happens until the first fetch lands, a local C# call that normally takes milliseconds, and 2 seconds is the ceiling. Without it, a picker opened early could offer a restricted text; making it opt-in would add API for a startup-only edge case.)
• M18: Disabled ProjectSelector rows now take pointer events, so a disabled, bound-but-closed row's "Open" button would become clickable. (fixed during review: the Open button is not rendered on a disabled row. A new test failed before the fix.)

Author response: the author asked for the reviewer's recommendation on each item, accepted fixing M1–M7, M12–M16 and M18, including the key rename in M3, and chose to skip M8–M11 and M17 for the reasons given.

Template Propagation

Shared Regions Modified

None.

Extension Config Changes

• [n/a] extensions/src/platform-scripture/contributions/localizedStrings.json: extension-specific, no propagation needed
• [n/a] extensions/src/platform-scripture/contributions/projectSettings.json: extension-specific, no propagation needed

Positive Observations

• Additive API. All API additions are optional or additive: a new optional prop, an optional field, a new method, a new setting and new types. No existing export was removed, narrowed or reordered. The types used by the new signatures are exported where extension developers can reach them.
• The setting follows an existing pattern. It follows PB_IS_PUBLISHED exactly: a get branch, a rejected set, a ProjectSettingsNames constant and a hidden projectSettings.json contribution. The C# wire shape is pinned by CopyrightNotice_SerializesToTheShapeTheFrontEndReads. CopyrightNotice tells consumers to treat an unknown kind as none, so the union can grow safely.
• Restrictions fail safe. A missing localized string falls back to the key, so a restricted row stays disabled. A failed refresh keeps the last known restrictions rather than clearing them.
• Hidden tabs are handled. At the measuring site, a comment explains that the banner's ResizeObserver catches up when the tab is shown, as .claude/rules/cross-view-sync-hidden-views.md requires. A test pins it.
• Accessibility and RTL:
  • Names are isolated in <bdi>, and the permissions URL is forced left-to-right.
  • Copyright paragraphs use dir="auto".
  • The external link has a hidden "opens in browser" description.
  • The details dialog replaces the unlocalized corner ✕ with a localized Close, and focus returns to "More info" when it closes.
  • The resource picker's disabled rows stay reachable and pass their reason to screen readers.
• Layout. The banner matches its neighbour SyncBlockedBanner and sits outside the scrolling area. It clamps to two lines, offering Show more only when the text overflows. Narrow Text Collection cells get an indicator instead.
• Localization. Every string is localized in all 33 platform-scripture locales. copyright-notice-strings.test.ts checks that each locale has every key with the same placeholders.
• Tests at every layer:
  • C#: licensing, backed by a survey of 1,819 DBL texts; notice and serialization; ListModelTextRestrictions; IsRestrictedAsBase.
  • Front end: the restrictions cache; the banner, indicator and panels; the resource picker, Team Layout and Manage Books wiring; guards that keep clicks and keys from a portalled dialog out of the Text Collection grid.
• Reuse. The refactors shared code rather than copying it: resolveModelTextProjectId is now shared by the model-text panel and its web view, and ResourceRowCells avoids duplicating the picker row markup.
• Housekeeping:
  • Comments are forward-facing.
  • The ADR entry, adr-biblica-license-notice-computed-setting, is in byte-order slug position and records the rejected alternatives.
  • No shadcn-ui files were modified.
  • The keyboard shortcuts catalog is still accurate.

Interview Notes

Purpose (author): "Show a banner on traditionally published Biblica texts explaining the copyright information."

Design explanation (Step 3.3): The author explained that Matt T provided the list of resources that must show the Biblica notice, and that the list was backed up programmatically by checking each resource's copyright; a text on the list gets the banner. The assistant filled in the code-level detail and the author accepted it:

• Only resources are checked.
• A resource on the list always gets the notice.
• The copyright rule also catches Biblica texts not on the list, such as texts added to the DBL later. A few Open texts are exempted by id.
• The same check drives the banner and the picker restrictions.

The copyright rule matched exactly the 55 listed texts among the 1,819 surveyed.

Scope decision, Paratext 9 parity: The author first expected the Biblica notice to show on editable projects too. After discussing it, they agreed to keep Paratext 9's behaviour:

• A "Notification:" copyright banner shows on any project.
• The Biblica restricted-license notice shows on resources only, because an editable project is the user's own translation.

The TSDoc was corrected to say exactly this.

Deliberate choices for the reviewer:

• Dismissal matches Paratext 9. A dismissed banner stays dismissed for that pane until the pane switches to another text and back.
• No end-to-end test. A DBL resource can't exist in an isolated e2e profile, so the e2e test was deleted. Unit and component tests cover the behaviour.
• UI-only enforcement. The model/base restriction is enforced only in the pickers. An existing selection is kept and shows the banner.
• Manage Books "Create based on" is in scope. It uses ProjectSummary.IsRestrictedAsBase.
• Keyboard gap. cmdk skips disabled items with the keyboard, so Manage Books' reason is reachable by pointer hover only (M9, follow-up).
• Translations. The notice strings were translated by AI into all 33 platform-scripture locales without native-speaker review, at the author's direction. The core key %restrictedModelOrBaseText_disabledReason% exists in en and es only, like the other resourcePicker_* keys.
• The tooltip keeps Ian's ticket wording.
• Biblica's wording is verbatim. "Outside of Paratext" in the details text is Biblica's required license text.
• Follow-up for a shared copyright UI. Enhanced Resources has its own copyright ribbon and dialog (M8).
• The details link opens through platform.openWindow. The web views' allowPopups was deliberately not widened.

Unresolved items: none. The author could explain every finding.

In-Review Quality Check

Every check passes, and none of them needed a fix.

• npm run typecheck: pass.
• ESLint: 0 errors across all changed files, per workspace. The full npm run lint takes over 40 minutes locally, so it was scoped to the changed files.
• Prettier --check: clean on all changed files.
• CSharpier: no changes.
• npm test: pass.
  • Core: 5,915 passed.
  • Workspaces: all pass, including platform-scripture-editor (2,093), platform-scripture (647) and platform-get-resources (133).
  • platform-bible-react: 1,092 unit tests passed, plus the changed stories.
  • The full run hit some timeouts under CPU load. Each of those files passed when rerun alone, and the ones outside this branch were web-view.component.test.tsx, comment-list.stories and comment-thread.stories.
• dotnet test c-sharp-tests/: 2,401 passed, 0 failed.

Rebased onto main (bbd52be5ac3, 16 new commits). Nine files conflicted, and main's changes were kept in each:

• The resource picker's truncating cells and fixed column widths.
• Team Layout's new picker dialog.
• ProjectSelector's indicator tooltips.
• The resource and model text panels' zoom area. The banner sits above it, so it stays at interface scale.
• Manage Books' fullName.

Two of main's tests needed updating for this branch: one ProjectSelector test's query, and a source-contract test that now pins the banner between the resource selector and the zoom area.

After the rebase:

• Checks: typecheck and the C# licensing/restriction tests (681) pass, and lint and Prettier are clean on the resolved files.
• Tests:
  • Dialogs: 163.
  • Picker and selector: 217, with the Open-button test re-checked by removing its fix.
  • Manage Books and platform-get-resources: 191.
  • platform-scripture-editor: 2,133.

Suggested Review Focus

• BiblicaLicensing.IsRestrictedLicense:

  • the list-then-copyright-rule order
  • the Open-text exemptions by id
  • whether the copyright rule should stay as a safety net or be removed in favour of the list alone

  The author explained the list at a product level; walk through the fallback rule together.

• Paratext 9 parity scope. Is showing "Notification:" banners on editable projects, and the Biblica notice on resources only, the product decision we want?

• Second feature: disabling restricted texts in the model and base pickers. Review its public API (getDisabledReason, disableRestrictedModelTexts, listModelTextRestrictions, isRestrictedAsModelText), and confirm that UI-only enforcement is acceptable.

• ProjectSelector disabled rows now take pointer events. This is a shared component, so check other consumers.

• The up-to-2-second first wait in getCachedResources and getLocalNonDblResources (M17).

• Follow-ups to file. The Manage Books keyboard reachability for disabled rows (M9), and a shared copyright UI in platform-bible-react (M8).

AI-assisted — Claude Code (Claude Opus 5.5)

🤖 Generated with Claude Code

---

This change is