From d47d86ef0f3f37854e745f43debb0c35d1c8dd26 Mon Sep 17 00:00:00 2001
From: Greg Trihus <gtryus@gmail.com>
Date: Thu, 3 Sep 2026 15:51:19 -0500
Subject: [PATCH 1/2] TT-7051 Enhance context and functionality for Sections &
 Passages in the project. Added definitions for Sections, Passage Cards, and
 Current Passage in CONTEXT.md. Updated PassageCard component to include
 unique IDs and data attributes for better accessibility. Modified PlanView to
 restore the Current Passage from local storage and ensure it is in view when
 loaded. Added tests to verify the restoration and scrolling behavior of the
 Current Passage card.

---
 CONTEXT.md                                    |  12 ++
 .../src/components/Sheet/PassageCard.tsx      |   5 +
 .../src/components/Sheet/PlanView.cy.tsx      | 202 +++++++++++++++++-
 .../src/components/Sheet/PlanView.tsx         |  38 +++-
 4 files changed, 250 insertions(+), 7 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index e1b4fb973..6493ca688 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -70,6 +70,18 @@ _Avoid_: Hierarchical; calling flat rows "passages"
 Project structure with sections containing numbered passages.
 _Avoid_: Flat
 
+**Sections & Passages**:
+The project page that lists sections and passages — desktop sheet or mobile cards.
+_Avoid_: PlanSheet; PlanView (implementation names)
+
+**Passage Card**:
+A mobile card for a passage (or section+passage) on Sections & Passages.
+_Avoid_: Sheet row; table cell
+
+**Current Passage**:
+The last passage the user opened for work, stored per user in local storage so Sections & Passages can restore focus.
+_Avoid_: Last row (desktop-sheet wording); selected row
+
 ## Publishing & Akuo
 
 Publishing in APM normally means releasing **oral content** to listeners — not transferring transcriptions. Text content follows the Paratext sync path instead.
diff --git a/src/renderer/src/components/Sheet/PassageCard.tsx b/src/renderer/src/components/Sheet/PassageCard.tsx
index 4468f9ab3..6a8a99827 100644
--- a/src/renderer/src/components/Sheet/PassageCard.tsx
+++ b/src/renderer/src/components/Sheet/PassageCard.tsx
@@ -52,9 +52,13 @@ export function PassageCard(props: IProps) {
     }
   };
 
+  const passageId = cardInfo.passage?.id;
+
   return (
     <Card
       elevation={3}
+      id={passageId ? `passage-card-${passageId}` : undefined}
+      data-cy={passageId ? `passage-card-${passageId}` : undefined}
       sx={{ minWidth: isMobileWidth ? '100%' : 275, maxWidth: 400 }}
     >
       <CardContent>
@@ -118,6 +122,7 @@ export function PassageCard(props: IProps) {
               </Box>
             )}
             <Button
+              data-cy="passage-card-step"
               sx={{
                 width: '100%',
                 position: 'relative',
diff --git a/src/renderer/src/components/Sheet/PlanView.cy.tsx b/src/renderer/src/components/Sheet/PlanView.cy.tsx
index d410bc03a..8adf259b4 100644
--- a/src/renderer/src/components/Sheet/PlanView.cy.tsx
+++ b/src/renderer/src/components/Sheet/PlanView.cy.tsx
@@ -20,6 +20,8 @@ import {
 } from '../../model';
 import { RecordIdentity } from '@orbit/records';
 import { PublishDestinationEnum } from '../../crud/usePublishDestination';
+import { Box } from '@mui/material';
+import { LocalKey, localUserKey } from '../../utils/localUserKey';
 
 // Mock dependencies
 const createMockLiveQuery = (data: any[] = []) => ({
@@ -30,10 +32,20 @@ const createMockLiveQuery = (data: any[] = []) => ({
   query: () => data,
 });
 
+type PassageKeyPair = { localId: string; remoteId: string };
+
+const createPassageKeyMap = (passages: PassageKeyPair[]) => ({
+  keyToId: (_table: string, _key: string, remoteId: string) =>
+    passages.find((p) => p.remoteId === remoteId)?.localId,
+  idToKey: (_table: string, _key: string, localId: string) =>
+    passages.find((p) => p.localId === localId)?.remoteId,
+});
+
 // Create mock memory that can return section and organization records
 const createMockMemory = (
   sections: SectionD[] = [],
-  organizations: any[] = []
+  organizations: any[] = [],
+  keyMap?: ReturnType<typeof createPassageKeyMap>
 ): Memory => {
   return {
     cache: {
@@ -78,6 +90,7 @@ const createMockMemory = (
       patch: () => {}, // Add a simple patch method
     },
     update: () => {},
+    keyMap,
   } as unknown as Memory;
 };
 
@@ -277,7 +290,11 @@ describe('PlanView', { tags: '@smoke' }, () => {
     globalStateOverrides = {},
     initialEntries: string[] = ['/project/test-prj'],
     sections: SectionD[] = [],
-    organizationName: string = 'Test Organization'
+    organizationName: string = 'Test Organization',
+    options: {
+      scrollHeight?: number;
+      keyMap?: ReturnType<typeof createPassageKeyMap>;
+    } = {}
   ) => {
     const initialState = createInitialState(globalStateOverrides);
     const planContextState = createMockPlanContextState(planContextOverrides);
@@ -300,7 +317,11 @@ describe('PlanView', { tags: '@smoke' }, () => {
       },
     ];
 
-    const memory = createMockMemory(sections, mockOrganizations);
+    const memory = createMockMemory(
+      sections,
+      mockOrganizations,
+      options.keyMap
+    );
 
     // Mock the cache to return organizations
     memory.cache.query = (queryFn: (q: any) => any) => {
@@ -327,6 +348,8 @@ describe('PlanView', { tags: '@smoke' }, () => {
       return queryFn(mockQueryBuilder);
     };
 
+    const planView = <PlanView {...props} />;
+
     cy.mount(
       <MemoryRouter initialEntries={initialEntries}>
         <Provider store={mockStore}>
@@ -338,7 +361,20 @@ describe('PlanView', { tags: '@smoke' }, () => {
                   setState: cy.stub(),
                 }}
               >
-                <PlanView {...props} />
+                {options.scrollHeight ? (
+                  <Box
+                    data-cy="plan-view-scroller"
+                    sx={{
+                      height: options.scrollHeight,
+                      overflowY: 'auto',
+                      overflowX: 'hidden',
+                    }}
+                  >
+                    {planView}
+                  </Box>
+                ) : (
+                  planView
+                )}
               </PlanContext.Provider>
             </DataProvider>
           </GlobalProvider>
@@ -347,6 +383,62 @@ describe('PlanView', { tags: '@smoke' }, () => {
     );
   };
 
+  const createManyPassages = (count: number): ISheet[] =>
+    Array.from({ length: count }, (_, i) => {
+      const n = i + 1;
+      return createMockPassage({
+        sectionSeq: n,
+        passageSeq: 1,
+        reference: `${n}:1`,
+        step: `Step ${n}`,
+        passage: {
+          id: `passage-${n}`,
+          type: 'passage',
+          attributes: {
+            sequencenum: 1,
+            book: 'GEN',
+            reference: `${n}:1`,
+            state: '',
+            hold: false,
+            title: '',
+            lastComment: '',
+            stepComplete: '{}',
+            dateCreated: '',
+            dateUpdated: '',
+            lastModifiedBy: 0,
+          },
+          keys: {
+            remoteId: String(n),
+          },
+        },
+      });
+    });
+
+  const keyPairsFromPassages = (rowInfo: ISheet[]): PassageKeyPair[] =>
+    rowInfo
+      .filter((r) => r.passage?.id)
+      .map((r) => ({
+        localId: r.passage!.id,
+        remoteId: String(r.passage!.keys?.remoteId ?? r.passage!.id),
+      }));
+
+  const assertCardInScrollerViewport = (passageLocalId: string) => {
+    cy.get('[data-cy="plan-view-scroller"]').then(($scroller) => {
+      cy.get(`[data-cy="passage-card-${passageLocalId}"]`).then(($card) => {
+        const scrollerRect = $scroller[0].getBoundingClientRect();
+        const cardRect = $card[0].getBoundingClientRect();
+        expect(
+          cardRect.bottom,
+          'card bottom should be below scroller top'
+        ).to.be.gte(scrollerRect.top);
+        expect(
+          cardRect.top,
+          'card top should be above scroller bottom'
+        ).to.be.lte(scrollerRect.bottom);
+      });
+    });
+  };
+
   it('should render Grid container', () => {
     const rowInfo: ISheet[] = [];
     const bookMap = createMockBookNameMap();
@@ -954,4 +1046,106 @@ describe('PlanView', { tags: '@smoke' }, () => {
     cy.get('div[class*="MuiCard-root"]').should('be.visible');
   });
 
+  it('restores scroll so the Current Passage card is in view', () => {
+    const rowInfo = createManyPassages(12);
+    const bookMap = createMockBookNameMap();
+    const keyMap = createPassageKeyMap(keyPairsFromPassages(rowInfo));
+
+    cy.window().then((win) => {
+      win.localStorage.setItem(LocalKey.userId, 'test-user-id');
+      win.localStorage.setItem(localUserKey(LocalKey.passage), '10');
+    });
+
+    mountPlanView(
+      {
+        rowInfo,
+        bookMap,
+        publishingView: false,
+        handlePublish: mockHandlePublish,
+        handleGraphic: mockHandleGraphic,
+      },
+      {},
+      {},
+      ['/project/test-prj'],
+      [],
+      'Test Organization',
+      { scrollHeight: 280, keyMap }
+    );
+
+    cy.get('[data-cy="passage-card-passage-10"]', { timeout: 5000 }).should(
+      'exist'
+    );
+    assertCardInScrollerViewport('passage-10');
+  });
+
+  it('remembers Current Passage when the step button is clicked', () => {
+    const rowInfo = createManyPassages(4);
+    const bookMap = createMockBookNameMap();
+    const keyMap = createPassageKeyMap(keyPairsFromPassages(rowInfo));
+
+    cy.window().then((win) => {
+      win.localStorage.setItem(LocalKey.userId, 'test-user-id');
+      win.localStorage.removeItem(localUserKey(LocalKey.passage));
+    });
+
+    mountPlanView(
+      {
+        rowInfo,
+        bookMap,
+        publishingView: false,
+        handlePublish: mockHandlePublish,
+        handleGraphic: mockHandleGraphic,
+      },
+      {},
+      {},
+      ['/project/test-prj'],
+      [],
+      'Test Organization',
+      { keyMap }
+    );
+
+    cy.get('[data-cy="passage-card-passage-3"]', { timeout: 5000 })
+      .find('[data-cy="passage-card-step"]')
+      .click();
+
+    cy.window().then((win) => {
+      expect(win.localStorage.getItem(localUserKey(LocalKey.passage))).to.equal(
+        '3'
+      );
+    });
+  });
+
+  it('does not scroll when Current Passage is missing from rowInfo', () => {
+    const rowInfo = createManyPassages(12);
+    const bookMap = createMockBookNameMap();
+    const keyMap = createPassageKeyMap(keyPairsFromPassages(rowInfo));
+
+    cy.window().then((win) => {
+      win.localStorage.setItem(LocalKey.userId, 'test-user-id');
+      win.localStorage.setItem(localUserKey(LocalKey.passage), '999');
+    });
+
+    mountPlanView(
+      {
+        rowInfo,
+        bookMap,
+        publishingView: false,
+        handlePublish: mockHandlePublish,
+        handleGraphic: mockHandleGraphic,
+      },
+      {},
+      {},
+      ['/project/test-prj'],
+      [],
+      'Test Organization',
+      { scrollHeight: 280, keyMap }
+    );
+
+    cy.get('[data-cy="passage-card-passage-1"]', { timeout: 5000 }).should(
+      'be.visible'
+    );
+    cy.get('[data-cy="plan-view-scroller"]').should(($scroller) => {
+      expect($scroller[0].scrollTop).to.eq(0);
+    });
+  });
 });
diff --git a/src/renderer/src/components/Sheet/PlanView.tsx b/src/renderer/src/components/Sheet/PlanView.tsx
index 6aea4293e..82268642b 100644
--- a/src/renderer/src/components/Sheet/PlanView.tsx
+++ b/src/renderer/src/components/Sheet/PlanView.tsx
@@ -1,4 +1,4 @@
-import { useContext, useMemo, useRef, useState } from 'react';
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { shallowEqual, useSelector } from 'react-redux';
 import {
   ISheet,
@@ -18,6 +18,7 @@ import { Button, GrowingSpacer } from '../../control';
 import {
   isPersonalTeam,
   PublishDestinationEnum,
+  remoteIdGuid,
   usePublishDestination,
 } from '../../crud';
 import { useGlobal } from '../../context/useGlobal';
@@ -27,6 +28,12 @@ import { useSectionIdDescription } from './useSectionIdDescription';
 import ConfirmPublishDialog from '../ConfirmPublishDialog';
 import { rowTypes } from './rowTypes';
 import { PlanContext } from '../../context/PlanContext';
+import {
+  LocalKey,
+  localUserKey,
+  rememberCurrentPassage,
+} from '../../utils';
+import { RecordKeyMap } from '@orbit/records';
 
 interface IProps {
   rowInfo: ISheet[];
@@ -47,11 +54,13 @@ export function PlanView(props: IProps) {
   const [view, setView] = useState('');
   const [confirmPublish, setConfirmPublish] = useState(false);
   const publishRow = useRef<number>(-1);
+  const restoredRef = useRef(false);
   const { isMovement } = rowTypes(rowInfo);
   const teams = useOrbitData<OrganizationD[]>('organization');
   const getDescription = useSectionIdDescription();
   const t: IPlanSheetStrings = useSelector(planSheetSelector, shallowEqual);
   const [teamId] = useGlobal('organization');
+  const [memory] = useGlobal('memory');
   const { isPublished } = usePublishDestination();
   const isPersonal = useMemo(
     () => isPersonalTeam(teamId, teams),
@@ -63,11 +72,34 @@ export function PlanView(props: IProps) {
   };
 
   const handleViewStep = (passageIndex: number) => {
-    const passageRemoteId = rowInfo[passageIndex].passage?.keys?.remoteId;
-
+    const passage = rowInfo[passageIndex].passage;
+    const passageRemoteId = passage?.keys?.remoteId;
+    if (passage?.id) {
+      void rememberCurrentPassage(memory, passage.id);
+    }
     setView(`/detail/${prjId}/${passageRemoteId}`);
   };
 
+  useEffect(() => {
+    if (restoredRef.current || !rowInfo.length) return;
+    const lastPasId = localStorage.getItem(localUserKey(LocalKey.passage));
+    if (!lastPasId) return;
+    const pasGuid =
+      remoteIdGuid(
+        'passage',
+        lastPasId,
+        memory?.keyMap as RecordKeyMap
+      ) || lastPasId;
+    const row = rowInfo.findIndex((r) => r.passage?.id === pasGuid);
+    if (row < 0) return;
+    const el = document.querySelector(
+      `[data-cy="passage-card-${pasGuid}"]`
+    ) as HTMLElement | null;
+    if (!el) return;
+    restoredRef.current = true;
+    el.scrollIntoView({ block: 'nearest', behavior: 'auto' });
+  }, [rowInfo, memory]);
+
   const publishConfirm = async (destinations: PublishDestinationEnum[]) => {
     setConfirmPublish(false);
     handlePublish(publishRow.current, destinations);

From 0e96de5607da36c678f197c844c6ff5e276a3c91 Mon Sep 17 00:00:00 2001
From: Greg Trihus <gtryus@gmail.com>
Date: Thu, 3 Sep 2026 16:13:35 -0500
Subject: [PATCH 2/2] TT-7051 Enhance PassageCard and PlanView components to
 support current passage highlighting. Added isCurrent prop to PassageCard for
 accessibility and visual indication. Updated PlanView to manage current
 passage state and ensure it is scrolled into view. Modified tests to verify
 current passage behavior.

---
 .../src/components/Sheet/PassageCard.tsx      | 13 +++++++-
 .../src/components/Sheet/PlanView.cy.tsx      | 14 ++++++--
 .../src/components/Sheet/PlanView.tsx         | 33 +++++++++++--------
 3 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/src/renderer/src/components/Sheet/PassageCard.tsx b/src/renderer/src/components/Sheet/PassageCard.tsx
index 6a8a99827..569246d0c 100644
--- a/src/renderer/src/components/Sheet/PassageCard.tsx
+++ b/src/renderer/src/components/Sheet/PassageCard.tsx
@@ -19,6 +19,7 @@ interface IProps {
   onGraphicClick?: () => void;
   isPlaying: boolean;
   isPersonal?: boolean;
+  isCurrent?: boolean;
 }
 
 export function PassageCard(props: IProps) {
@@ -30,6 +31,7 @@ export function PassageCard(props: IProps) {
     onGraphicClick,
     isPlaying,
     isPersonal,
+    isCurrent,
   } = props;
   const getDescription = useSectionIdDescription();
   const t: ICardsStrings = useSelector(cardsSelector, shallowEqual);
@@ -59,7 +61,16 @@ export function PassageCard(props: IProps) {
       elevation={3}
       id={passageId ? `passage-card-${passageId}` : undefined}
       data-cy={passageId ? `passage-card-${passageId}` : undefined}
-      sx={{ minWidth: isMobileWidth ? '100%' : 275, maxWidth: 400 }}
+      aria-current={isCurrent ? 'true' : undefined}
+      sx={{
+        minWidth: isMobileWidth ? '100%' : 275,
+        maxWidth: 400,
+        ...(isCurrent && {
+          outline: '2px solid',
+          outlineColor: 'primary.light',
+          outlineOffset: 2,
+        }),
+      }}
     >
       <CardContent>
         <Box sx={{ display: 'flex', alignItems: 'center' }}>
diff --git a/src/renderer/src/components/Sheet/PlanView.cy.tsx b/src/renderer/src/components/Sheet/PlanView.cy.tsx
index 8adf259b4..4e211beee 100644
--- a/src/renderer/src/components/Sheet/PlanView.cy.tsx
+++ b/src/renderer/src/components/Sheet/PlanView.cy.tsx
@@ -1046,7 +1046,7 @@ describe('PlanView', { tags: '@smoke' }, () => {
     cy.get('div[class*="MuiCard-root"]').should('be.visible');
   });
 
-  it('restores scroll so the Current Passage card is in view', () => {
+  it('restores highlight and scroll so the Current Passage card is in view', () => {
     const rowInfo = createManyPassages(12);
     const bookMap = createMockBookNameMap();
     const keyMap = createPassageKeyMap(keyPairsFromPassages(rowInfo));
@@ -1072,9 +1072,17 @@ describe('PlanView', { tags: '@smoke' }, () => {
       { scrollHeight: 280, keyMap }
     );
 
-    cy.get('[data-cy="passage-card-passage-10"]', { timeout: 5000 }).should(
-      'exist'
+    cy.get('[data-cy="passage-card-passage-10"]', { timeout: 5000 })
+      .should('exist')
+      .and('have.attr', 'aria-current', 'true');
+    cy.get('[data-cy="passage-card-passage-1"]').should(
+      'not.have.attr',
+      'aria-current'
     );
+    cy.get('[data-cy="plan-view-scroller"]').should(($scroller) => {
+      expect($scroller[0].scrollTop, 'scroller moved to Current Passage').to.be
+        .greaterThan(0);
+    });
     assertCardInScrollerViewport('passage-10');
   });
 
diff --git a/src/renderer/src/components/Sheet/PlanView.tsx b/src/renderer/src/components/Sheet/PlanView.tsx
index 82268642b..dd3b75da5 100644
--- a/src/renderer/src/components/Sheet/PlanView.tsx
+++ b/src/renderer/src/components/Sheet/PlanView.tsx
@@ -67,6 +67,20 @@ export function PlanView(props: IProps) {
     [teamId, teams]
   );
 
+  const currentPassageId = useMemo(() => {
+    if (!rowInfo.length) return undefined;
+    const lastPasId = localStorage.getItem(localUserKey(LocalKey.passage));
+    if (!lastPasId) return undefined;
+    const pasGuid =
+      remoteIdGuid(
+        'passage',
+        lastPasId,
+        memory?.keyMap as RecordKeyMap
+      ) || lastPasId;
+    const row = rowInfo.findIndex((r) => r.passage?.id === pasGuid);
+    return row >= 0 ? pasGuid : undefined;
+  }, [rowInfo, memory]);
+
   const onPlayStatus = (mediaId: string) => {
     setSrcMediaId(mediaId);
   };
@@ -81,24 +95,14 @@ export function PlanView(props: IProps) {
   };
 
   useEffect(() => {
-    if (restoredRef.current || !rowInfo.length) return;
-    const lastPasId = localStorage.getItem(localUserKey(LocalKey.passage));
-    if (!lastPasId) return;
-    const pasGuid =
-      remoteIdGuid(
-        'passage',
-        lastPasId,
-        memory?.keyMap as RecordKeyMap
-      ) || lastPasId;
-    const row = rowInfo.findIndex((r) => r.passage?.id === pasGuid);
-    if (row < 0) return;
+    if (restoredRef.current || !currentPassageId) return;
     const el = document.querySelector(
-      `[data-cy="passage-card-${pasGuid}"]`
+      `[data-cy="passage-card-${currentPassageId}"]`
     ) as HTMLElement | null;
     if (!el) return;
     restoredRef.current = true;
     el.scrollIntoView({ block: 'nearest', behavior: 'auto' });
-  }, [rowInfo, memory]);
+  }, [currentPassageId, rowInfo]);
 
   const publishConfirm = async (destinations: PublishDestinationEnum[]) => {
     setConfirmPublish(false);
@@ -201,6 +205,9 @@ export function PlanView(props: IProps) {
               }
               isPlaying={mediaId === srcMediaId}
               isPersonal={isPersonal}
+              isCurrent={
+                !!currentPassageId && row.passage?.id === currentPassageId
+              }
             />
           );
         } else {