From 2133d2e03957d9069c95119382e1eb90cb1100b3 Mon Sep 17 00:00:00 2001
From: Duncan Appleby <duncan@progressrpg.com>
Date: Fri, 14 Aug 2026 10:10:44 +0100
Subject: [PATCH 1/6] feat: parent task chip, due-date split, timestamp
 tooltip, subtask creation

- Display a parent task chip in the task edit modal (with remove/select),
  and split the due-date input into separate date/time fields (#762).
- Move task timestamp display (created/modified/completed) out of the
  inline summary into a clock-icon tooltip on the edit modal's title row
  (#764).
- Rework "Add a subtask": clicking it now opens the same task edit/detail
  modal used everywhere else, seeded with a blank, unsaved draft, instead
  of adding a "Subtask of X" chip before the task input (#774). The draft
  is only actually created once its name has been genuinely edited (via
  usePlayerItemModal's existing no-op-edit guard); closing the modal
  without editing the name discards the draft with no API call.
- Add PlayerItemList `hiddenItemIds` (keep an item deep-linkable without
  rendering it as a row) and `onModalClose` (notify the caller which item's
  modal just closed) to support the draft-subtask flow.
---
 .../PlayerItemList/PlayerItemList.tsx         |  40 +++-
 .../TasksPanel/TasksPanel.module.scss         |  21 ++
 .../components/TasksPanel/TasksPanel.test.tsx | 110 ++++++++-
 .../src/components/TasksPanel/TasksPanel.tsx  | 224 ++++++++++++------
 .../components/TasksPanel/useTasksPanel.tsx   |  98 +++++++-
 frontend/src/utils/formatUtils.test.ts        |  69 ++++--
 frontend/src/utils/formatUtils.ts             |  42 +++-
 7 files changed, 478 insertions(+), 126 deletions(-)

diff --git a/frontend/src/components/PlayerItemList/PlayerItemList.tsx b/frontend/src/components/PlayerItemList/PlayerItemList.tsx
index 9d0f2e9c..0617d707 100644
--- a/frontend/src/components/PlayerItemList/PlayerItemList.tsx
+++ b/frontend/src/components/PlayerItemList/PlayerItemList.tsx
@@ -1,4 +1,4 @@
-import React, { useEffect, useMemo } from "react";
+import React, { useCallback, useEffect, useMemo } from "react";
 import classNames from "classnames";
 
 import Button from "../Button/Button";
@@ -33,6 +33,8 @@ interface PlayerItemListProps<T extends { id?: string | number; name?: string }>
   getItemKey?: (item: T, index: number) => string | number;
   renderItemMeta?: (item: T) => React.ReactNode;
   renderEditSummary?: (item: T, saveHelpers: SaveStatusHelpers) => React.ReactNode;
+  /** Rendered next to the name input in the edit modal's title row (e.g. an icon button). */
+  renderTitleRowActions?: (item: T) => React.ReactNode;
   onEdit?: (item: T, name: string, callbacks?: SaveCallbacks) => void;
   onDelete?: (item: T) => void;
   hoverEdit?: boolean;
@@ -47,6 +49,10 @@ interface PlayerItemListProps<T extends { id?: string | number; name?: string }>
   /** Called once the requested `openItemId` has been opened, so the caller can clear it. */
   onOpenItemHandled?: () => void;
   getChildren?: (item: T) => T[] | undefined;
+  /** Ids of items present in `items` (e.g. for the deep-link lookup) that should not be rendered as rows. */
+  hiddenItemIds?: Set<string | number>;
+  /** Called with the item whose edit modal just closed (via Close, backdrop, or Escape). */
+  onModalClose?: (item: T) => void;
 }
 
 export default function PlayerItemList<T extends { id?: string | number; name?: string }>({
@@ -59,6 +65,7 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
   getItemKey,
   renderItemMeta,
   renderEditSummary,
+  renderTitleRowActions,
   onEdit,
   onDelete,
   hoverEdit = false,
@@ -71,6 +78,8 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
   openItemId,
   onOpenItemHandled,
   getChildren,
+  hiddenItemIds,
+  onModalClose,
 }: PlayerItemListProps<T>) {
   const {
     activeFilterKey,
@@ -125,6 +134,13 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
     onOpenItemHandled?.();
   }, [openItemId, items, handleOpenItem, onOpenItemHandled]);
 
+  // Wraps handleModalClose so a consumer (e.g. to discard an unsaved draft
+  // item) learns which item's modal just closed via Close/backdrop/Escape.
+  const closeModal = useCallback(() => {
+    if (activeItem) onModalClose?.(activeItem);
+    handleModalClose();
+  }, [activeItem, onModalClose, handleModalClose]);
+
   const canToggleComplete = typeof onToggleComplete === "function";
   const canEdit = typeof onEdit === "function";
   const canDelete = typeof onDelete === "function";
@@ -140,16 +156,23 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
     return ids;
   }, [items, getChildren]);
 
+  // Items present in `items` only so the deep-link/openItemId lookup can find
+  // them (e.g. an unsaved draft) are excluded from the rendered rows.
+  const visibleDisplayItems = useMemo(() => {
+    if (!hiddenItemIds || hiddenItemIds.size === 0) return displayItems;
+    return displayItems.filter((item) => item.id === undefined || !hiddenItemIds.has(item.id));
+  }, [displayItems, hiddenItemIds]);
+
   // Sort/filter controls only apply to top-level items; a child keeps its
   // place directly after its parent (in `getChildren`'s order) rather than
   // being reordered independently.
   const flatDisplayItems = useMemo(() => {
-    if (!getChildren) return displayItems;
-    const topLevel = displayItems.filter(
+    if (!getChildren) return visibleDisplayItems;
+    const topLevel = visibleDisplayItems.filter(
       (item) => item.id === undefined || !childIds.has(item.id)
     );
     return topLevel.flatMap((item) => [item, ...(getChildren(item) ?? [])]);
-  }, [displayItems, getChildren, childIds]);
+  }, [visibleDisplayItems, getChildren, childIds]);
 
   const renderRow = (item: T): React.ReactNode => (
     <>
@@ -283,7 +306,7 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
               ? `Delete ${itemLabelLower}?`
               : `Edit ${itemLabelLower}`
           }
-          onClose={handleModalClose}
+          onClose={closeModal}
           onBack={confirmingDelete ? () => setConfirmingDelete(false) : undefined}
           backLabel="Back"
         >
@@ -328,17 +351,20 @@ export default function PlayerItemList<T extends { id?: string | number; name?:
                       autoFocus
                       onKeyDown={(event) => {
                         if (event.key === "Enter") handleEditSave();
-                        if (event.key === "Escape") handleModalClose();
+                        if (event.key === "Escape") closeModal();
                       }}
                     />
                   ) : null}
+                  {renderTitleRowActions && liveActiveItem
+                    ? renderTitleRowActions(liveActiveItem)
+                    : null}
                 </div>
               ) : null}
               {modalSummary ? (
                 <div className={styles.editConfirmMeta}>{modalSummary}</div>
               ) : null}
               <div className={styles.editConfirmActions}>
-                <Button variant="secondary" onClick={handleModalClose}>
+                <Button variant="secondary" onClick={closeModal}>
                   Close
                 </Button>
                 {canDelete ? (
diff --git a/frontend/src/components/TasksPanel/TasksPanel.module.scss b/frontend/src/components/TasksPanel/TasksPanel.module.scss
index ca842fd1..b38d1f24 100644
--- a/frontend/src/components/TasksPanel/TasksPanel.module.scss
+++ b/frontend/src/components/TasksPanel/TasksPanel.module.scss
@@ -99,6 +99,27 @@
   gap: sp.$spacing-sm;
 }
 
+.timestampButton {
+  flex-shrink: 0;
+  height: sp.$form-control-height;
+  width: sp.$form-control-height;
+  padding: 0;
+  border: 1px solid rgba(c.$color-border-primary, 0.35);
+  border-radius: sp.$form-control-radius;
+  background: transparent;
+  color: inherit;
+  font-size: 1rem;
+  line-height: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+
+  &:hover {
+    border-color: rgba(c.$color-border-primary, 0.55);
+  }
+}
+
 .timestampLabel {
   font-weight: 600;
   margin-bottom: 2px;
diff --git a/frontend/src/components/TasksPanel/TasksPanel.test.tsx b/frontend/src/components/TasksPanel/TasksPanel.test.tsx
index 6ddb5e8f..a503b5cf 100644
--- a/frontend/src/components/TasksPanel/TasksPanel.test.tsx
+++ b/frontend/src/components/TasksPanel/TasksPanel.test.tsx
@@ -359,7 +359,7 @@ describe("TasksPanel", () => {
       expect(screen.queryByText("Child subtask")).not.toBeInTheDocument();
     });
 
-    it("pre-fills the add-task form with a parent chip via the add-subtask row action", async () => {
+    it("opens the task detail modal for a blank draft subtask without creating one yet", async () => {
       const user = userEvent.setup({ pointerEventsCheck: 0 });
       mockUseTasks.mockReturnValue({
         isLoading: false,
@@ -369,15 +369,65 @@ describe("TasksPanel", () => {
 
       await user.click(screen.getByRole("button", { name: "Add subtask to Parent project task" }));
 
-      expect(screen.getByText(/Subtask of Parent project task/)).toBeInTheDocument();
+      const dialog = await screen.findByRole("dialog");
+      expect(within(dialog).getByLabelText("task name")).toHaveValue("");
+      expect(createMutate).not.toHaveBeenCalled();
+    });
+
+    it("creates the subtask only once its draft name has actually been edited, then opens the persisted task", async () => {
+      const user = userEvent.setup({ pointerEventsCheck: 0 });
+      const newSubtask = { ...childTask, id: 7, name: "New task" };
+      createMutate.mockImplementation((_data, callbacks) => {
+        callbacks?.onSuccess?.(newSubtask);
+      });
+      mockUseTasks.mockReturnValue({
+        isLoading: false,
+        data: [parentTask],
+      });
+      const { rerender } = renderTasksPanel();
+
+      await user.click(screen.getByRole("button", { name: "Add subtask to Parent project task" }));
+      const dialog = await screen.findByRole("dialog");
+      const input = within(dialog).getByLabelText("task name");
+      await user.type(input, "New task");
+      await user.tab();
+
+      expect(createMutate).toHaveBeenCalledWith(
+        { name: "New task", parent: 3 },
+        expect.objectContaining({ onSuccess: expect.any(Function), onError: expect.any(Function) }),
+      );
+
+      // The new subtask isn't in `items` until the tasks query refetches with it included.
+      mockUseTasks.mockReturnValue({
+        isLoading: false,
+        data: [parentTask, newSubtask],
+      });
+      rerender(
+        <TooltipProvider>
+          <TasksPanel />
+        </TooltipProvider>,
+      );
 
-      const input = screen.getByLabelText("new task");
-      await user.type(input, "Buy groceries");
-      await user.click(screen.getByRole("button", { name: "Add subtask" }));
+      const reopenedDialog = await screen.findByRole("dialog");
+      expect(within(reopenedDialog).getByDisplayValue("New task")).toBeInTheDocument();
+    });
+
+    it("discards the draft subtask, without creating anything, when its modal is closed unedited", async () => {
+      const user = userEvent.setup({ pointerEventsCheck: 0 });
+      mockUseTasks.mockReturnValue({
+        isLoading: false,
+        data: [parentTask],
+      });
+      renderTasksPanel();
+
+      await user.click(screen.getByRole("button", { name: "Add subtask to Parent project task" }));
+      const dialog = await screen.findByRole("dialog");
+      await user.click(within(dialog).getByRole("button", { name: "Close" }));
 
       await waitFor(() => {
-        expect(createMutate).toHaveBeenCalledWith({ name: "Buy groceries", parent: 3 });
+        expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
       });
+      expect(createMutate).not.toHaveBeenCalled();
     });
 
     it("disables the parent picker for a task that already has subtasks", async () => {
@@ -406,7 +456,7 @@ describe("TasksPanel", () => {
       );
 
       const dueDateInput = screen.getByLabelText("Due date");
-      await user.type(dueDateInput, "2026-06-01T09:00");
+      await user.type(dueDateInput, "2026-06-01");
       await user.tab();
 
       await waitFor(() => {
@@ -416,5 +466,51 @@ describe("TasksPanel", () => {
         );
       });
     });
+
+    it("defaults the date to today when only a time is set", async () => {
+      const user = userEvent.setup();
+      renderTasksPanel();
+
+      await user.click(
+        screen.getAllByRole("button", { name: "Edit task Morning routine" })[0],
+      );
+
+      const dueTimeInput = screen.getByLabelText("Due time");
+      await user.type(dueTimeInput, "0900");
+      await user.tab();
+
+      await waitFor(() => {
+        expect(updateMutate).toHaveBeenCalledWith(
+          { id: 1, data: { due_at: expect.any(String) } },
+          expect.objectContaining({ onSuccess: expect.any(Function), onError: expect.any(Function) }),
+        );
+      });
+
+      const lastCall = updateMutate.mock.calls.at(-1) as [{ data: { due_at: string } }, unknown];
+      const committedDate = new Date(lastCall[0].data.due_at);
+      const today = new Date();
+      expect(committedDate.getFullYear()).toBe(today.getFullYear());
+      expect(committedDate.getMonth()).toBe(today.getMonth());
+      expect(committedDate.getDate()).toBe(today.getDate());
+    });
+  });
+
+  describe("timestamps tooltip", () => {
+    it("shows Created/Modified/Completed on click of the clock button", async () => {
+      const user = userEvent.setup();
+      renderTasksPanel();
+
+      await user.click(
+        screen.getAllByRole("button", { name: "Edit task Morning routine" })[0],
+      );
+
+      expect(screen.queryByText("Created", { selector: "div" })).not.toBeInTheDocument();
+
+      await user.click(screen.getByRole("button", { name: "View task timestamps" }));
+
+      expect(screen.getByText("Created", { selector: "div" })).toBeInTheDocument();
+      expect(screen.getByText("Modified", { selector: "div" })).toBeInTheDocument();
+      expect(screen.getByText("Completed", { selector: "div" })).toBeInTheDocument();
+    });
   });
 });
diff --git a/frontend/src/components/TasksPanel/TasksPanel.tsx b/frontend/src/components/TasksPanel/TasksPanel.tsx
index 3da46e7a..148ea471 100644
--- a/frontend/src/components/TasksPanel/TasksPanel.tsx
+++ b/frontend/src/components/TasksPanel/TasksPanel.tsx
@@ -1,4 +1,4 @@
-import React from "react";
+import React, { useRef } from "react";
 import classNames from "classnames";
 
 import EntitySearchInput from "../EntitySearchInput/EntitySearchInput";
@@ -6,7 +6,7 @@ import Button from "../Button/Button";
 import PlayerItemList from "../PlayerItemList/PlayerItemList";
 import Tooltip from "../Tooltip/Tooltip";
 import { isTaskComplete, taskSortOptions, useTasksPanel, type ItemRecord } from "./useTasksPanel";
-import { toDatetimeLocalValue, fromDatetimeLocalValue } from "../../utils/formatUtils";
+import { toDateInputValue, toTimeInputValue, fromDateAndTimeInputValues } from "../../utils/formatUtils";
 import styles from "./TasksPanel.module.scss";
 
 interface TasksPanelProps {
@@ -31,9 +31,11 @@ export default function TasksPanel({
     visibleTasks,
     getChildren,
     topLevelTasks,
-    addSubtaskParent,
+    pendingOpenTaskId,
+    hiddenItemIds,
     startAddSubtask,
-    clearAddSubtaskParent,
+    clearPendingOpenTaskId,
+    discardDraftTask,
     handleCreateTask,
     handleSubmitForm,
     handleEdit,
@@ -48,35 +50,27 @@ export default function TasksPanel({
     updateTask,
   } = useTasksPanel(openTaskId, onOpenNote);
 
+  // Only one task's edit summary is ever open at a time (it renders inside a modal), so a
+  // single pair of refs is enough to read the sibling input's value when committing due_at.
+  const dueDateInputRef = useRef<HTMLInputElement>(null);
+  const dueTimeInputRef = useRef<HTMLInputElement>(null);
+
   if (isLoading) return <p>Loading tasks...</p>;
 
   return (
     <div className={styles.page}>
       <div className={styles.content}>
       <form className={styles.addTaskForm} onSubmit={handleSubmitForm}>
-        {addSubtaskParent && (
-          <span className={styles.parentChip}>
-            Subtask of {addSubtaskParent.name}
-            <button
-              type="button"
-              className={styles.parentChipClear}
-              aria-label="Clear subtask parent"
-              onClick={clearAddSubtaskParent}
-            >
-              ×
-            </button>
-          </span>
-        )}
         <EntitySearchInput
           type="task"
           value={newName}
           onChange={(v) => setNewName(v)}
-          onCreate={(name) => handleCreateTask(name, { parent: addSubtaskParent?.id ?? undefined })}
-          placeholder={addSubtaskParent ? "New subtask name" : "New task name"}
+          onCreate={(name) => handleCreateTask(name)}
+          placeholder="New task name"
           className={styles.addTaskInput}
         />
         <Button type="submit">
-          <span className={styles.addButtonText}>{addSubtaskParent ? "Add subtask" : "Add task"}</span>
+          <span className={styles.addButtonText}>Add task</span>
           <span className={styles.addButtonIcon} aria-hidden="true">✓</span>
         </Button>
       </form>
@@ -108,27 +102,19 @@ export default function TasksPanel({
             );
           }}
           renderEditSummary={(taskItem, saveHelpers) => {
+            if (taskItem.id < 0) {
+              // An unsaved draft subtask: nothing to show or edit here yet
+              // (due date, parent, notes) until it's actually been created.
+              return <div className={styles.timestampLabel}>Type a name to create this subtask.</div>;
+            }
+
             const summary = getTaskEditSummary(taskItem);
             const hasSubtasks = (taskItem.subtask_count ?? 0) > 0;
             const parentOptions = topLevelTasks.filter((t) => t.id !== taskItem.id);
+            const parentTask = topLevelTasks.find((t) => t.id === taskItem.parent) ?? null;
 
             return (
               <>
-                <div className={styles.taskTimestamps}>
-                  <div>
-                    <div className={styles.timestampLabel}>Created</div>
-                    <div>{summary.created}</div>
-                  </div>
-                  <div>
-                    <div className={styles.timestampLabel}>Modified</div>
-                    <div>{summary.modified}</div>
-                  </div>
-                  <div>
-                    <div className={styles.timestampLabel}>Completed</div>
-                    <div>{summary.completed}</div>
-                  </div>
-                </div>
-                <hr></hr>
                 <div>
                   Total time: {summary.totalTime}
                 </div>
@@ -154,20 +140,51 @@ export default function TasksPanel({
                   })()
                 ) : null}
                 <div className={styles.dueDateRow}>
-                  <label className={styles.timestampLabel} htmlFor="task-due-at">
+                  <label className={styles.timestampLabel} htmlFor="task-due-at-date">
                     Due date
                   </label>
                   <input
-                    id="task-due-at"
-                    type="datetime-local"
+                    id="task-due-at-date"
+                    ref={dueDateInputRef}
+                    type="date"
                     className={styles.dueDateInput}
-                    defaultValue={toDatetimeLocalValue(taskItem.due_at)}
-                    onBlur={(event) => {
+                    defaultValue={toDateInputValue(taskItem.due_at)}
+                    onBlur={() => {
                       saveHelpers.reportSaving();
                       updateTask.mutate(
                         {
                           id: taskItem.id,
-                          data: { due_at: fromDatetimeLocalValue(event.target.value) },
+                          data: {
+                            due_at: fromDateAndTimeInputValues(
+                              dueDateInputRef.current?.value ?? "",
+                              dueTimeInputRef.current?.value ?? "",
+                            ),
+                          },
+                        },
+                        { onSuccess: saveHelpers.reportSaved, onError: saveHelpers.reportError },
+                      );
+                    }}
+                  />
+                  <input
+                    aria-label="Due time"
+                    ref={dueTimeInputRef}
+                    type="time"
+                    className={styles.dueDateInput}
+                    defaultValue={toTimeInputValue(taskItem.due_at)}
+                    onBlur={() => {
+                      if (dueTimeInputRef.current?.value && dueDateInputRef.current && !dueDateInputRef.current.value) {
+                        dueDateInputRef.current.value = toDateInputValue(new Date().toISOString());
+                      }
+                      saveHelpers.reportSaving();
+                      updateTask.mutate(
+                        {
+                          id: taskItem.id,
+                          data: {
+                            due_at: fromDateAndTimeInputValues(
+                              dueDateInputRef.current?.value ?? "",
+                              dueTimeInputRef.current?.value ?? "",
+                            ),
+                          },
                         },
                         { onSuccess: saveHelpers.reportSaved, onError: saveHelpers.reportError },
                       );
@@ -177,6 +194,8 @@ export default function TasksPanel({
                     <Button
                       variant="secondary"
                       onClick={() => {
+                        if (dueDateInputRef.current) dueDateInputRef.current.value = "";
+                        if (dueTimeInputRef.current) dueTimeInputRef.current.value = "";
                         saveHelpers.reportSaving();
                         updateTask.mutate(
                           { id: taskItem.id, data: { due_at: null } },
@@ -192,41 +211,95 @@ export default function TasksPanel({
                   <label className={styles.timestampLabel} htmlFor="task-parent">
                     Parent task
                   </label>
-                  <Tooltip
-                    content={
-                      hasSubtasks
-                        ? "This task already has subtasks and can't be nested under another task."
-                        : undefined
-                    }
-                  >
-                    <select
-                      id="task-parent"
-                      className={styles.parentSelect}
-                      disabled={hasSubtasks}
-                      defaultValue={taskItem.parent ?? ""}
-                      onChange={(event) => {
-                        saveHelpers.reportSaving();
-                        updateTask.mutate(
-                          {
-                            id: taskItem.id,
-                            data: { parent: event.target.value ? Number(event.target.value) : null },
-                          },
-                          { onSuccess: saveHelpers.reportSaved, onError: saveHelpers.reportError },
-                        );
-                      }}
+                  {parentTask ? (
+                    <span className={styles.parentChip}>
+                      {parentTask.name}
+                      <button
+                        type="button"
+                        className={styles.parentChipClear}
+                        aria-label={`Remove parent task ${parentTask.name}`}
+                        onClick={() => {
+                          saveHelpers.reportSaving();
+                          updateTask.mutate(
+                            { id: taskItem.id, data: { parent: null } },
+                            { onSuccess: saveHelpers.reportSaved, onError: saveHelpers.reportError },
+                          );
+                        }}
+                      >
+                        ×
+                      </button>
+                    </span>
+                  ) : (
+                    <Tooltip
+                      content={
+                        hasSubtasks
+                          ? "This task already has subtasks and can't be nested under another task."
+                          : undefined
+                      }
                     >
-                      <option value="">No parent</option>
-                      {parentOptions.map((option) => (
-                        <option key={option.id} value={option.id}>
-                          {option.name}
-                        </option>
-                      ))}
-                    </select>
-                  </Tooltip>
+                      <select
+                        id="task-parent"
+                        className={styles.parentSelect}
+                        disabled={hasSubtasks}
+                        defaultValue=""
+                        onChange={(event) => {
+                          saveHelpers.reportSaving();
+                          updateTask.mutate(
+                            {
+                              id: taskItem.id,
+                              data: { parent: event.target.value ? Number(event.target.value) : null },
+                            },
+                            { onSuccess: saveHelpers.reportSaved, onError: saveHelpers.reportError },
+                          );
+                        }}
+                      >
+                        <option value="">No parent</option>
+                        {parentOptions.map((option) => (
+                          <option key={option.id} value={option.id}>
+                            {option.name}
+                          </option>
+                        ))}
+                      </select>
+                    </Tooltip>
+                  )}
                 </div>
               </>
             );
           }}
+          renderTitleRowActions={(task) => {
+            if (task.id < 0) return null;
+            const summary = getTaskEditSummary(task);
+            return (
+              <Tooltip
+                placement="bottom"
+                align="end"
+                content={
+                  <div className={styles.taskTimestamps}>
+                    <div>
+                      <div className={styles.timestampLabel}>Created</div>
+                      <div>{summary.created}</div>
+                    </div>
+                    <div>
+                      <div className={styles.timestampLabel}>Modified</div>
+                      <div>{summary.modified}</div>
+                    </div>
+                    <div>
+                      <div className={styles.timestampLabel}>Completed</div>
+                      <div>{summary.completed}</div>
+                    </div>
+                  </div>
+                }
+              >
+                <button
+                  type="button"
+                  className={styles.timestampButton}
+                  aria-label="View task timestamps"
+                >
+                  🕐
+                </button>
+              </Tooltip>
+            );
+          }}
           hoverEdit
           renderRowActions={(task) => (
             <>
@@ -262,8 +335,13 @@ export default function TasksPanel({
           )}
           onEdit={handleEdit}
           onDelete={handleDelete}
-          openItemId={openTaskId}
-          onOpenItemHandled={onOpenTaskHandled}
+          openItemId={openTaskId ?? pendingOpenTaskId}
+          onOpenItemHandled={() => {
+            onOpenTaskHandled?.();
+            clearPendingOpenTaskId();
+          }}
+          hiddenItemIds={hiddenItemIds}
+          onModalClose={discardDraftTask}
           sortOptions={taskSortOptions}
           controls={
             <Button
diff --git a/frontend/src/components/TasksPanel/useTasksPanel.tsx b/frontend/src/components/TasksPanel/useTasksPanel.tsx
index af963a66..35d02e00 100644
--- a/frontend/src/components/TasksPanel/useTasksPanel.tsx
+++ b/frontend/src/components/TasksPanel/useTasksPanel.tsx
@@ -13,6 +13,32 @@ import { TASKS_HIDE_COMPLETED_KEY } from "../../utils/userPreferences";
 
 export type ItemRecord = Task & { [key: string]: unknown };
 
+// A client-side-only placeholder for a not-yet-created subtask. It's given a
+// negative id (real task ids are always positive) so it can share the same
+// items array, id-matching deep-link, and edit-modal machinery as real
+// tasks, without ever colliding with one or being mistaken for one.
+function makeDraftSubtask(parentId: number): ItemRecord {
+  const now = new Date().toISOString();
+  return {
+    id: -Date.now(),
+    name: "",
+    description: "",
+    player: 0,
+    project: null,
+    created_at: now,
+    last_updated: now,
+    is_complete: false,
+    completed_at: null,
+    first_completed_at: null,
+    due_at: null,
+    parent: parentId,
+    subtask_count: 0,
+    total_time: 0,
+    total_records: 0,
+    last_worked_on: null,
+  };
+}
+
 export interface TaskEditSummary {
   created: string;
   modified: string;
@@ -116,7 +142,8 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
       return true;
     }
   });
-  const [addSubtaskParent, setAddSubtaskParent] = useState<ItemRecord | null>(null);
+  const [pendingOpenTaskId, setPendingOpenTaskId] = useState<number | null>(null);
+  const [draftTask, setDraftTask] = useState<ItemRecord | null>(null);
 
   useEffect(() => {
     if (!completionReward) return;
@@ -176,9 +203,17 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
     });
   }, [safeTasks, hideCompleted, openTaskId]);
 
-  const visibleTasks = useMemo(
-    () => groupedTasks.flatMap((group) => [group.parent, ...group.children]),
-    [groupedTasks]
+  const visibleTasks = useMemo(() => {
+    const flat = groupedTasks.flatMap((group) => [group.parent, ...group.children]);
+    // The draft only needs to be present so PlayerItemList's id-matching
+    // deep-link can find and open it; it's kept out of the rendered rows via
+    // hiddenItemIds below.
+    return draftTask ? [...flat, draftTask] : flat;
+  }, [groupedTasks, draftTask]);
+
+  const hiddenItemIds = useMemo(
+    () => (draftTask ? new Set<number>([draftTask.id]) : undefined),
+    [draftTask]
   );
 
   const childrenByGroupParentId = useMemo(
@@ -223,7 +258,6 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
         ...(options?.due_at !== undefined ? { due_at: options.due_at } : {}),
       });
       setNewName("");
-      setAddSubtaskParent(null);
     },
     [createTask]
   );
@@ -231,28 +265,62 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
   const handleSubmitForm = useCallback(
     (event: React.FormEvent<HTMLFormElement>) => {
       event.preventDefault();
-      handleCreateTask(newName, { parent: addSubtaskParent?.id ?? undefined });
+      handleCreateTask(newName);
     },
-    [handleCreateTask, newName, addSubtaskParent]
+    [handleCreateTask, newName]
   );
 
   const startAddSubtask = useCallback((task: ItemRecord) => {
-    setAddSubtaskParent(task);
+    const draft = makeDraftSubtask(task.id);
+    setDraftTask(draft);
+    // Reuses the same one-shot open mechanism as reopening a just-created
+    // task: PlayerItemList's deep-link effect only fires while openItemId is
+    // non-null, and onOpenItemHandled clears it straight back to null once
+    // the modal's opened, so it doesn't keep re-opening (and resetting the
+    // in-progress edit) on every subsequent render/keystroke.
+    setPendingOpenTaskId(draft.id);
   }, []);
 
-  const clearAddSubtaskParent = useCallback(() => {
-    setAddSubtaskParent(null);
+  const clearPendingOpenTaskId = useCallback(() => {
+    setPendingOpenTaskId(null);
+  }, []);
+
+  // Discards the draft if its modal is what just closed, i.e. the user
+  // opened "Add subtask" and closed it again without giving it a name.
+  const discardDraftTask = useCallback((item: ItemRecord) => {
+    setDraftTask((current) => (current && current.id === item.id ? null : current));
   }, []);
 
   const handleEdit = useCallback(
     (task: ItemRecord, name: string, callbacks?: { onSuccess?: () => void; onError?: () => void }) => {
+      // A draft subtask isn't persisted until it's actually given a name;
+      // commitNameEdit only calls onEdit once the name has genuinely
+      // changed, so this only fires on the user's first real edit.
+      if (task.id < 0) {
+        createTask.mutate(
+          { name, parent: task.parent },
+          {
+            onSuccess: (created) => {
+              setDraftTask(null);
+              setPendingOpenTaskId(created.id);
+              callbacks?.onSuccess?.();
+            },
+            onError: callbacks?.onError,
+          }
+        );
+        return;
+      }
       updateTask.mutate({ id: task.id, data: { name } }, callbacks);
     },
-    [updateTask]
+    [createTask, updateTask]
   );
 
   const handleDelete = useCallback(
     (task: Task) => {
+      if (task.id < 0) {
+        setDraftTask(null);
+        return;
+      }
       deleteTask.mutate(task.id);
     },
     [deleteTask]
@@ -260,6 +328,7 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
 
   const handleToggleComplete = useCallback(
     (task: Task) => {
+      if (task.id < 0) return;
       const completing = !isTaskComplete(task);
       updateTask.mutate(
         {
@@ -331,9 +400,12 @@ export function useTasksPanel(openTaskId?: number | null, onOpenNote?: (noteId:
     groupedTasks,
     getChildren,
     topLevelTasks,
-    addSubtaskParent,
+    pendingOpenTaskId,
+    draftTask,
+    hiddenItemIds,
     startAddSubtask,
-    clearAddSubtaskParent,
+    clearPendingOpenTaskId,
+    discardDraftTask,
     handleCreateTask,
     handleSubmitForm,
     handleEdit,
diff --git a/frontend/src/utils/formatUtils.test.ts b/frontend/src/utils/formatUtils.test.ts
index 474acf97..55ec7daf 100644
--- a/frontend/src/utils/formatUtils.test.ts
+++ b/frontend/src/utils/formatUtils.test.ts
@@ -2,8 +2,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   formatDueAt,
-  toDatetimeLocalValue,
-  fromDatetimeLocalValue,
+  toDateInputValue,
+  toTimeInputValue,
+  fromDateAndTimeInputValues,
   isOverdue,
 } from "./formatUtils";
 
@@ -85,33 +86,69 @@ describe("formatDueAt", () => {
   });
 });
 
-describe("toDatetimeLocalValue", () => {
+describe("toDateInputValue", () => {
   it("returns an empty string when null", () => {
-    expect(toDatetimeLocalValue(null)).toBe("");
+    expect(toDateInputValue(null)).toBe("");
   });
 
-  it("formats a valid ISO string as YYYY-MM-DDTHH:mm", () => {
-    const value = toDatetimeLocalValue("2026-05-01T08:30:00.000Z");
-    expect(value).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/);
+  it("formats a valid ISO string as YYYY-MM-DD", () => {
+    const value = toDateInputValue("2026-05-01T08:30:00.000Z");
+    expect(value).toMatch(/^\d{4}-\d{2}-\d{2}$/);
   });
 });
 
-describe("fromDatetimeLocalValue", () => {
-  it("returns null for an empty string", () => {
-    expect(fromDatetimeLocalValue("")).toBeNull();
+describe("toTimeInputValue", () => {
+  it("returns an empty string when null", () => {
+    expect(toTimeInputValue(null)).toBe("");
+  });
+
+  it("formats a valid ISO string as HH:mm", () => {
+    const value = toTimeInputValue("2026-05-01T08:30:00.000Z");
+    expect(value).toMatch(/^\d{2}:\d{2}$/);
+  });
+
+  it("returns an empty string for the 23:59 no-time-set sentinel", () => {
+    const localMidnight = new Date(2026, 4, 1, 23, 59);
+    expect(toTimeInputValue(localMidnight.toISOString())).toBe("");
+  });
+});
+
+describe("fromDateAndTimeInputValues", () => {
+  it("returns null when both inputs are empty", () => {
+    expect(fromDateAndTimeInputValues("", "")).toBeNull();
   });
 
-  it("converts a datetime-local value to an ISO string", () => {
-    const iso = fromDatetimeLocalValue("2026-05-01T08:30");
+  it("converts a date and time to an ISO string", () => {
+    const iso = fromDateAndTimeInputValues("2026-05-01", "08:30");
     expect(iso).not.toBeNull();
     expect(new Date(iso as string).getFullYear()).toBe(2026);
   });
 
-  it("round-trips through toDatetimeLocalValue", () => {
+  it("defaults the date to today when only a time is given", () => {
+    const iso = fromDateAndTimeInputValues("", "08:30") as string;
+    const result = new Date(iso);
+    const today = new Date();
+    expect(result.getFullYear()).toBe(today.getFullYear());
+    expect(result.getMonth()).toBe(today.getMonth());
+    expect(result.getDate()).toBe(today.getDate());
+    expect(result.getHours()).toBe(8);
+    expect(result.getMinutes()).toBe(30);
+  });
+
+  it("defaults the time to 23:59 when only a date is given", () => {
+    const iso = fromDateAndTimeInputValues("2026-05-01", "") as string;
+    const result = new Date(iso);
+    expect(result.getHours()).toBe(23);
+    expect(result.getMinutes()).toBe(59);
+  });
+
+  it("round-trips through toDateInputValue and toTimeInputValue", () => {
     const original = "2026-05-01T08:30:00.000Z";
-    const localValue = toDatetimeLocalValue(original);
-    const roundTripped = fromDatetimeLocalValue(localValue);
-    expect(toDatetimeLocalValue(roundTripped)).toBe(localValue);
+    const dateValue = toDateInputValue(original);
+    const timeValue = toTimeInputValue(original);
+    const roundTripped = fromDateAndTimeInputValues(dateValue, timeValue);
+    expect(toDateInputValue(roundTripped)).toBe(dateValue);
+    expect(toTimeInputValue(roundTripped)).toBe(timeValue);
   });
 });
 
diff --git a/frontend/src/utils/formatUtils.ts b/frontend/src/utils/formatUtils.ts
index 3bbd83b4..a7e976b1 100644
--- a/frontend/src/utils/formatUtils.ts
+++ b/frontend/src/utils/formatUtils.ts
@@ -122,25 +122,47 @@ export function formatDueAt(dueAt: string | null): string {
   return `${weekday} ${day}${ordinalSuffix(day)} ${month}`;
 }
 
-export function toDatetimeLocalValue(dueAt: string | null): string {
+// Sentinel time used to represent "date set, no time set" — see fromDateAndTimeInputValues.
+const END_OF_DAY_TIME = "23:59";
+
+function todayLocalDateValue(): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const now = new Date();
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+export function toDateInputValue(dueAt: string | null): string {
   if (!dueAt) return "";
   const date = new Date(dueAt);
   if (Number.isNaN(date.getTime())) return "";
 
   const pad = (n: number) => String(n).padStart(2, "0");
-  const year = date.getFullYear();
-  const month = pad(date.getMonth() + 1);
-  const day = pad(date.getDate());
-  const hours = pad(date.getHours());
-  const minutes = pad(date.getMinutes());
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
 
-  return `${year}-${month}-${day}T${hours}:${minutes}`;
+export function toTimeInputValue(dueAt: string | null): string {
+  if (!dueAt) return "";
+  const date = new Date(dueAt);
+  if (Number.isNaN(date.getTime())) return "";
+
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const hours = date.getHours();
+  const minutes = date.getMinutes();
+  // 23:59 is the sentinel for "no time set" (see fromDateAndTimeInputValues), so it
+  // displays as an empty time field rather than a literal end-of-day time.
+  if (hours === 23 && minutes === 59) return "";
+
+  return `${pad(hours)}:${pad(minutes)}`;
 }
 
-export function fromDatetimeLocalValue(value: string): string | null {
-  if (!value) return null;
-  const date = new Date(value);
+export function fromDateAndTimeInputValues(dateValue: string, timeValue: string): string | null {
+  if (!dateValue && !timeValue) return null;
+
+  const effectiveDate = dateValue || todayLocalDateValue();
+  const effectiveTime = timeValue || END_OF_DAY_TIME;
+  const date = new Date(`${effectiveDate}T${effectiveTime}`);
   if (Number.isNaN(date.getTime())) return null;
+
   return date.toISOString();
 }
 

From 5d894c2cebc43878eab20f5013a4aaece05b3826 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 14 Aug 2026 09:24:04 +0000
Subject: [PATCH 2/6] Re-enable player-presence XP modifiers and add live
 character productivity

Re-enables handle_online_login, set_activity_active_modifiers, and
schedule_online_end (disabled in 870afd2 pending premium-XP isolation),
routing all modifier creation through the shared activate_link_modifier
helper (extended with a scope param so it can target PLAYER as well as
CHARACTER modifiers).

Stopping an activity no longer ends its activity_active modifier
immediately - ends_at is pushed out by a 5-minute grace window via
schedule_modifier_end, and starting another activity within that window
refreshes the same modifier row instead of dropping and reactivating it.

Adds progression.ap.get_productivity (baseline constant x live active
XpModifier multiplier) and Character.get_productivity as the authored,
live-read productivity signal called for in the issue - deliberately not
derived from lifetime AP total.

Closes #750

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N8Siy6MEuhLq9kCa3ujBwf
---
 character/models/character.py       |   9 +
 gameplay/services/xp_modifiers.py   | 251 +++++++++++-------------
 gameplay/tests/test_xp_modifiers.py | 288 ++++++++++++++++++++++++++++
 progression/ap.py                   |  22 +++
 progression/tests/test_ap.py        |  54 ++++++
 5 files changed, 481 insertions(+), 143 deletions(-)
 create mode 100644 gameplay/tests/test_xp_modifiers.py

diff --git a/character/models/character.py b/character/models/character.py
index c5ef0ad1..053c8573 100644
--- a/character/models/character.py
+++ b/character/models/character.py
@@ -520,6 +520,15 @@ def total_link_points(self):
         """
         return PlayerCharacterLink.total_link_points(self.links.all())
 
+    def get_productivity(self, now=None):
+        """
+        Live productivity signal - see progression.ap.get_productivity for
+        what drives it (authored baseline x current active XpModifiers).
+        """
+        from progression import ap
+
+        return ap.get_productivity(self, now=now)
+
 
 ########################################################################
 ####    PLAYER CHARACTER LINK MODEL
diff --git a/gameplay/services/xp_modifiers.py b/gameplay/services/xp_modifiers.py
index 66868536..d11832b5 100644
--- a/gameplay/services/xp_modifiers.py
+++ b/gameplay/services/xp_modifiers.py
@@ -13,20 +13,34 @@
 ACTIVITY_ACTIVE_KEY = "activity_active"
 ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER = 1.5
 ACTIVITY_ACTIVE_PLAYER_MULTIPLIER = 1.25
+# Grace window before an activity_active modifier actually ends once a
+# player stops timing, so a gap between a character's activity blocks (or a
+# quick pause/resume) doesn't drop and reactivate the boost - see issue #750.
+ACTIVITY_ACTIVE_GRACE_MINUTES = 5
 
 
 @transaction.atomic
 def activate_link_modifier(
-    *, link, key: str, multiplier, duration=None, ends_at=None, now=None
+    *,
+    link,
+    key: str,
+    multiplier,
+    scope=XpModifier.Scope.CHARACTER,
+    duration=None,
+    ends_at=None,
+    now=None,
 ):
     now = now or timezone.now()
     if ends_at is None and duration is not None:
         ends_at = now + duration
 
+    owner_field = "character" if scope == XpModifier.Scope.CHARACTER else "player"
+    owner = link.character if scope == XpModifier.Scope.CHARACTER else link.player
+
     mod, _created = XpModifier.objects.update_or_create(
-        scope=XpModifier.Scope.CHARACTER,
-        character=link.character,
+        scope=scope,
         key=key,
+        **{owner_field: owner},
         defaults={
             "multiplier": multiplier,
             "starts_at": now,
@@ -78,81 +92,47 @@ def schedule_modifier_end(
 
 @transaction.atomic
 def schedule_online_end(link: PlayerCharacterLink, cooldown_minutes=30):
-    # player_online modifiers are temporarily disabled while premium activity XP
-    # is being isolated and verified.
-    return None
-    # now = timezone.now()
-    # ends_at = now + timedelta(minutes=cooldown_minutes)
-    #
-    # mod = (
-    #     XpModifier.objects.filter(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=PLAYER_ONLINE_KEY,
-    #     )
-    #     .order_by("-starts_at")
-    #     .first()
-    # )
-    # if mod:
-    #     mod.multiplier = PLAYER_ONLINE_MULTIPLIER
-    #     mod.is_active = True
-    #     mod.save(update_fields=["multiplier", "is_active"])
-    # else:
-    #     mod = XpModifier.objects.create(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=PLAYER_ONLINE_KEY,
-    #         multiplier=PLAYER_ONLINE_MULTIPLIER,
-    #         starts_at=now,
-    #         ends_at=None,
-    #         is_active=True,
-    #     )
-    #
-    # return schedule_modifier_end(mod=mod, ends_at=ends_at)
+    """
+    Called when a player disconnects: keep the player_online modifier active
+    for `cooldown_minutes` instead of ending it immediately, so a brief
+    reconnect doesn't cost the character its boost, then let the scheduled
+    Celery task end it if the player doesn't come back in time.
+    """
+    now = timezone.now()
+    ends_at = now + timedelta(minutes=cooldown_minutes)
+
+    mod = activate_link_modifier(
+        link=link,
+        key=PLAYER_ONLINE_KEY,
+        multiplier=PLAYER_ONLINE_MULTIPLIER,
+        now=now,
+    )
+    return schedule_modifier_end(mod=mod, ends_at=ends_at)
 
 
 @transaction.atomic
 def handle_online_login(player: Player):
-    # player_online modifiers are temporarily disabled while premium activity XP
-    # is being isolated and verified.
-    return None
-    # link = player.active_link
-    # if not link:
-    #     return None
-    # link = PlayerCharacterLink.objects.get(id=link.id)
-    # mod = (
-    #     XpModifier.objects.filter(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=PLAYER_ONLINE_KEY,
-    #     )
-    #     .order_by("-starts_at")
-    #     .first()
-    # )
-    #
-    # now = timezone.now()
-    #
-    # if not mod:
-    #     mod = XpModifier.objects.create(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=PLAYER_ONLINE_KEY,
-    #         multiplier=PLAYER_ONLINE_MULTIPLIER,
-    #         starts_at=now,
-    #         ends_at=None,
-    #         is_active=True,
-    #         task_id=None,
-    #     )
-    #     return mod
-    # if mod.task_id:
-    #     current_app.control.revoke(mod.task_id)
-    #     mod.task_id = None
-    #
-    # mod.multiplier = PLAYER_ONLINE_MULTIPLIER
-    # mod.is_active = True
-    # mod.ends_at = None
-    # mod.save(update_fields=["multiplier", "is_active", "ends_at", "task_id"])
-    # return mod
+    """
+    Called whenever a player is confirmed online (login, or any
+    authenticated poll while connected): (re)activate the player_online
+    character modifier and cancel any cooldown-end task left over from a
+    previous disconnect.
+    """
+    link = player.active_link
+    if not link:
+        return None
+    link = PlayerCharacterLink.objects.select_related("character").get(id=link.id)
+
+    mod = activate_link_modifier(
+        link=link,
+        key=PLAYER_ONLINE_KEY,
+        multiplier=PLAYER_ONLINE_MULTIPLIER,
+    )
+    if mod.task_id:
+        current_app.control.revoke(mod.task_id)
+        mod.task_id = None
+        mod.save(update_fields=["task_id"])
+    return mod
 
 
 @transaction.atomic
@@ -162,73 +142,58 @@ def set_activity_active_modifiers(player: Player, *, is_active: bool):
 
     - Character gets a higher bonus while player is actively recording.
     - Player gets their own bonus while actively recording.
+
+    Stopping doesn't end the modifiers outright: `ends_at` is pushed out by
+    ACTIVITY_ACTIVE_GRACE_MINUTES and a Celery task is scheduled to end them
+    then. If the player starts another activity within that window,
+    activate_link_modifier's update_or_create refreshes the same modifier
+    row (and the pending end task is cancelled) rather than dropping and
+    reactivating it.
     """
-    # activity_active modifiers are temporarily disabled while premium activity
-    # XP is being isolated and verified.
-    return []
-    # link = player.active_link
-    # if not link:
-    #     return []
-    #
-    # link = PlayerCharacterLink.objects.select_related("character", "player").get(
-    #     id=link.id
-    # )
-    # now = timezone.now()
-    #
-    # character_mod = (
-    #     XpModifier.objects.filter(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=ACTIVITY_ACTIVE_KEY,
-    #     )
-    #     .order_by("-starts_at")
-    #     .first()
-    # )
-    # if not character_mod and is_active:
-    #     character_mod = XpModifier.objects.create(
-    #         scope=XpModifier.Scope.CHARACTER,
-    #         character=link.character,
-    #         key=ACTIVITY_ACTIVE_KEY,
-    #         multiplier=ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER,
-    #         starts_at=now,
-    #         ends_at=None,
-    #         is_active=True,
-    #         task_id=None,
-    #     )
-    # elif character_mod:
-    #     character_mod.multiplier = ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER
-    #     character_mod.is_active = is_active
-    #     character_mod.ends_at = None if is_active else now
-    #     character_mod.task_id = None
-    #     character_mod.save(
-    #         update_fields=["multiplier", "is_active", "ends_at", "task_id"]
-    #     )
-    #
-    # player_mod = (
-    #     XpModifier.objects.filter(
-    #         scope=XpModifier.Scope.PLAYER,
-    #         player=link.player,
-    #         key=ACTIVITY_ACTIVE_KEY,
-    #     )
-    #     .order_by("-starts_at")
-    #     .first()
-    # )
-    # if not player_mod and is_active:
-    #     player_mod = XpModifier.objects.create(
-    #         scope=XpModifier.Scope.PLAYER,
-    #         player=link.player,
-    #         key=ACTIVITY_ACTIVE_KEY,
-    #         multiplier=ACTIVITY_ACTIVE_PLAYER_MULTIPLIER,
-    #         starts_at=now,
-    #         ends_at=None,
-    #         is_active=True,
-    #         task_id=None,
-    #     )
-    # elif player_mod:
-    #     player_mod.multiplier = ACTIVITY_ACTIVE_PLAYER_MULTIPLIER
-    #     player_mod.is_active = is_active
-    #     player_mod.ends_at = None if is_active else now
-    #     player_mod.task_id = None
-    #     player_mod.save(update_fields=["multiplier", "is_active", "ends_at", "task_id"])
-    #
-    # return [m for m in [character_mod, player_mod] if m]
+    link = player.active_link
+    if not link:
+        return []
+
+    link = PlayerCharacterLink.objects.select_related("character", "player").get(
+        id=link.id
+    )
+
+    if is_active:
+        mods = [
+            activate_link_modifier(
+                link=link,
+                key=ACTIVITY_ACTIVE_KEY,
+                multiplier=ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER,
+                scope=XpModifier.Scope.CHARACTER,
+            ),
+            activate_link_modifier(
+                link=link,
+                key=ACTIVITY_ACTIVE_KEY,
+                multiplier=ACTIVITY_ACTIVE_PLAYER_MULTIPLIER,
+                scope=XpModifier.Scope.PLAYER,
+            ),
+        ]
+        for mod in mods:
+            if mod.task_id:
+                current_app.control.revoke(mod.task_id)
+                mod.task_id = None
+                mod.save(update_fields=["task_id"])
+        return mods
+
+    grace_ends_at = timezone.now() + timedelta(minutes=ACTIVITY_ACTIVE_GRACE_MINUTES)
+    mods = []
+    for scope, owner_field, owner in (
+        (XpModifier.Scope.CHARACTER, "character", link.character),
+        (XpModifier.Scope.PLAYER, "player", link.player),
+    ):
+        mod = (
+            XpModifier.objects.filter(
+                scope=scope, key=ACTIVITY_ACTIVE_KEY, **{owner_field: owner}
+            )
+            .order_by("-starts_at")
+            .first()
+        )
+        if mod and mod.is_active:
+            mods.append(schedule_modifier_end(mod=mod, ends_at=grace_ends_at))
+
+    return mods
diff --git a/gameplay/tests/test_xp_modifiers.py b/gameplay/tests/test_xp_modifiers.py
new file mode 100644
index 00000000..4420f5f3
--- /dev/null
+++ b/gameplay/tests/test_xp_modifiers.py
@@ -0,0 +1,288 @@
+from datetime import timedelta
+from decimal import Decimal
+from unittest.mock import MagicMock, patch
+
+from django.test import TestCase
+from django.utils import timezone
+
+from character.models import Character, PlayerCharacterLink
+from gameplay.models import XpModifier
+from gameplay.services import xp_modifiers as xpm
+from progression.models import ActivityDefinition, CharacterActivity
+
+from users.tests import user_factory
+
+
+def _linked_player_and_character():
+    user = user_factory(with_player=True)
+    player = user.player
+    character = Character.objects.create(given_name="Hero")
+    link = PlayerCharacterLink.objects.create(player=player, character=character)
+    return player, character, link
+
+
+class ActivateLinkModifierTests(TestCase):
+    def setUp(self):
+        self.player, self.character, self.link = _linked_player_and_character()
+
+    def test_defaults_to_character_scope(self):
+        mod = xpm.activate_link_modifier(
+            link=self.link, key="test_key", multiplier=Decimal("1.5")
+        )
+        self.assertEqual(mod.scope, XpModifier.Scope.CHARACTER)
+        self.assertEqual(mod.character_id, self.character.id)
+        self.assertIsNone(mod.player_id)
+        self.assertTrue(mod.is_active)
+        self.assertIsNone(mod.ends_at)
+
+    def test_can_target_player_scope(self):
+        mod = xpm.activate_link_modifier(
+            link=self.link,
+            key="test_key",
+            multiplier=Decimal("1.25"),
+            scope=XpModifier.Scope.PLAYER,
+        )
+        self.assertEqual(mod.scope, XpModifier.Scope.PLAYER)
+        self.assertEqual(mod.player_id, self.player.id)
+        self.assertIsNone(mod.character_id)
+
+    def test_second_call_updates_same_row_instead_of_duplicating(self):
+        first = xpm.activate_link_modifier(
+            link=self.link, key="test_key", multiplier=Decimal("1.5")
+        )
+        second = xpm.activate_link_modifier(
+            link=self.link, key="test_key", multiplier=Decimal("2.0")
+        )
+        self.assertEqual(first.id, second.id)
+        self.assertEqual(XpModifier.objects.filter(key="test_key").count(), 1)
+        self.assertEqual(second.multiplier, Decimal("2.0"))
+
+    def test_duration_computes_ends_at(self):
+        now = timezone.now()
+        mod = xpm.activate_link_modifier(
+            link=self.link,
+            key="test_key",
+            multiplier=Decimal("1.5"),
+            duration=timedelta(minutes=30),
+            now=now,
+        )
+        self.assertEqual(mod.ends_at, now + timedelta(minutes=30))
+
+
+class HandleOnlineLoginTests(TestCase):
+    def setUp(self):
+        self.user = user_factory(with_player=True)
+        self.player = self.user.player
+        self.character = Character.objects.create(given_name="Hero")
+
+    def test_returns_none_without_active_link(self):
+        self.assertIsNone(xpm.handle_online_login(self.player))
+        self.assertFalse(XpModifier.objects.exists())
+
+    def test_activates_indefinite_player_online_modifier(self):
+        PlayerCharacterLink.objects.create(player=self.player, character=self.character)
+        mod = xpm.handle_online_login(self.player)
+        self.assertIsNotNone(mod)
+        self.assertEqual(mod.key, xpm.PLAYER_ONLINE_KEY)
+        self.assertEqual(mod.scope, XpModifier.Scope.CHARACTER)
+        self.assertEqual(mod.character_id, self.character.id)
+        self.assertEqual(mod.multiplier, Decimal(str(xpm.PLAYER_ONLINE_MULTIPLIER)))
+        self.assertTrue(mod.is_active)
+        self.assertIsNone(mod.ends_at)
+
+    def test_relogin_cancels_pending_cooldown_end_task(self):
+        link = PlayerCharacterLink.objects.create(
+            player=self.player, character=self.character
+        )
+        mock_result = MagicMock(id="scheduled-task-id")
+        with patch.object(
+            xpm.end_online_boost, "apply_async", return_value=mock_result
+        ):
+            xpm.schedule_online_end(link)
+
+        mod = XpModifier.objects.get(key=xpm.PLAYER_ONLINE_KEY)
+        self.assertEqual(mod.task_id, "scheduled-task-id")
+        self.assertIsNotNone(mod.ends_at)
+
+        with patch.object(xpm, "current_app") as mock_app:
+            xpm.handle_online_login(self.player)
+
+        mock_app.control.revoke.assert_called_once_with("scheduled-task-id")
+        mod.refresh_from_db()
+        self.assertIsNone(mod.task_id)
+        self.assertIsNone(mod.ends_at)
+        self.assertTrue(mod.is_active)
+
+
+class ScheduleOnlineEndTests(TestCase):
+    def setUp(self):
+        self.player, self.character, self.link = _linked_player_and_character()
+
+    def test_schedules_end_after_cooldown_instead_of_ending_immediately(self):
+        mock_result = MagicMock(id="scheduled-task-id")
+        with patch.object(
+            xpm.end_online_boost, "apply_async", return_value=mock_result
+        ) as mock_apply_async:
+            xpm.schedule_online_end(self.link, cooldown_minutes=30)
+
+        mod = XpModifier.objects.get(key=xpm.PLAYER_ONLINE_KEY)
+        self.assertTrue(mod.is_active)
+        self.assertIsNotNone(mod.ends_at)
+        self.assertAlmostEqual(
+            mod.ends_at,
+            timezone.now() + timedelta(minutes=30),
+            delta=timedelta(seconds=5),
+        )
+        self.assertEqual(mod.task_id, "scheduled-task-id")
+        mock_apply_async.assert_called_once()
+        self.assertEqual(
+            mock_apply_async.call_args.kwargs["kwargs"], {"modifier_id": mod.id}
+        )
+
+
+class SetActivityActiveModifiersTests(TestCase):
+    def setUp(self):
+        self.player, self.character, self.link = _linked_player_and_character()
+
+    def test_returns_empty_list_without_active_link(self):
+        user = user_factory(with_player=True)
+        self.assertEqual(
+            xpm.set_activity_active_modifiers(user.player, is_active=True), []
+        )
+        self.assertFalse(XpModifier.objects.exists())
+
+    def test_activating_creates_character_and_player_modifiers(self):
+        mods = xpm.set_activity_active_modifiers(self.player, is_active=True)
+        self.assertEqual(len(mods), 2)
+
+        character_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.CHARACTER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+        self.assertEqual(character_mod.character_id, self.character.id)
+        self.assertEqual(
+            character_mod.multiplier,
+            Decimal(str(xpm.ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER)),
+        )
+        self.assertTrue(character_mod.is_active)
+        self.assertIsNone(character_mod.ends_at)
+
+        player_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.PLAYER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+        self.assertEqual(player_mod.player_id, self.player.id)
+        self.assertEqual(
+            player_mod.multiplier, Decimal(str(xpm.ACTIVITY_ACTIVE_PLAYER_MULTIPLIER))
+        )
+
+    def test_deactivating_without_prior_activation_does_nothing(self):
+        mods = xpm.set_activity_active_modifiers(self.player, is_active=False)
+        self.assertEqual(mods, [])
+        self.assertFalse(XpModifier.objects.exists())
+
+    def test_deactivating_extends_ends_at_instead_of_ending_immediately(self):
+        xpm.set_activity_active_modifiers(self.player, is_active=True)
+
+        mock_result = MagicMock(id="grace-task-id")
+        with patch.object(
+            xpm.end_online_boost, "apply_async", return_value=mock_result
+        ):
+            xpm.set_activity_active_modifiers(self.player, is_active=False)
+
+        character_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.CHARACTER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+        player_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.PLAYER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+
+        for mod in (character_mod, player_mod):
+            self.assertTrue(mod.is_active)
+            self.assertIsNotNone(mod.ends_at)
+            self.assertAlmostEqual(
+                mod.ends_at,
+                timezone.now() + timedelta(minutes=xpm.ACTIVITY_ACTIVE_GRACE_MINUTES),
+                delta=timedelta(seconds=5),
+            )
+            self.assertEqual(mod.task_id, "grace-task-id")
+
+    def test_reactivating_within_grace_window_refreshes_and_cancels_pending_end(self):
+        xpm.set_activity_active_modifiers(self.player, is_active=True)
+
+        mock_result = MagicMock(id="grace-task-id")
+        with patch.object(
+            xpm.end_online_boost, "apply_async", return_value=mock_result
+        ):
+            xpm.set_activity_active_modifiers(self.player, is_active=False)
+
+        with patch.object(xpm, "current_app") as mock_app:
+            xpm.set_activity_active_modifiers(self.player, is_active=True)
+
+        self.assertEqual(mock_app.control.revoke.call_count, 2)
+
+        character_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.CHARACTER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+        player_mod = XpModifier.objects.get(
+            scope=XpModifier.Scope.PLAYER, key=xpm.ACTIVITY_ACTIVE_KEY
+        )
+        for mod in (character_mod, player_mod):
+            self.assertTrue(mod.is_active)
+            self.assertIsNone(mod.ends_at)
+            self.assertIsNone(mod.task_id)
+
+        # Refreshed the existing rows rather than creating new ones.
+        self.assertEqual(
+            XpModifier.objects.filter(key=xpm.ACTIVITY_ACTIVE_KEY).count(), 2
+        )
+
+
+class CharacterActivityRewardConsumptionTests(TestCase):
+    """
+    Confirms CharacterActivity.get_xp_reward_summary() (progression/models.py)
+    still picks up the modifiers these functions create, now that they're
+    live again - see issue #750.
+    """
+
+    def setUp(self):
+        self.player, self.character, self.link = _linked_player_and_character()
+        self.activity_definition = ActivityDefinition.objects.create(
+            name="tending crops", kind=ActivityDefinition.Kind.WORK
+        )
+
+    def _make_activity(self, duration=600):
+        now = timezone.now()
+        return CharacterActivity.objects.create(
+            character=self.character,
+            activity_definition=self.activity_definition,
+            started_at=now - timedelta(seconds=duration),
+            duration=duration,
+        )
+
+    def test_no_active_modifiers_gives_unboosted_reward(self):
+        activity = self._make_activity()
+        summary = activity.get_xp_reward_summary()
+        self.assertEqual(summary["boost_multiplier"], 1)
+
+    def test_player_online_modifier_boosts_reward(self):
+        xpm.handle_online_login(self.player)
+        activity = self._make_activity()
+        summary = activity.get_xp_reward_summary()
+        self.assertEqual(summary["boost_multiplier"], xpm.PLAYER_ONLINE_MULTIPLIER)
+
+    def test_activity_active_modifier_boosts_reward(self):
+        xpm.set_activity_active_modifiers(self.player, is_active=True)
+        activity = self._make_activity()
+        summary = activity.get_xp_reward_summary()
+        self.assertEqual(
+            summary["boost_multiplier"], xpm.ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER
+        )
+
+    def test_stacked_modifiers_multiply(self):
+        xpm.handle_online_login(self.player)
+        xpm.set_activity_active_modifiers(self.player, is_active=True)
+        activity = self._make_activity()
+        summary = activity.get_xp_reward_summary()
+        expected = (
+            xpm.PLAYER_ONLINE_MULTIPLIER * xpm.ACTIVITY_ACTIVE_CHARACTER_MULTIPLIER
+        )
+        self.assertEqual(summary["boost_multiplier"], expected)
diff --git a/progression/ap.py b/progression/ap.py
index d5944b1f..0a64d4e7 100644
--- a/progression/ap.py
+++ b/progression/ap.py
@@ -79,3 +79,25 @@ def get_multiplier(person, now=None) -> Decimal:
         mult *= m.multiplier
 
     return mult
+
+
+# Authored baseline productivity for every character - flat for v1, may
+# later factor in role/mood/history (see issue #750).
+CHARACTER_BASELINE_PRODUCTIVITY = Decimal("1.0")
+
+
+def get_productivity(character, now=None) -> Decimal:
+    """
+    Live "how productive is this character right now" signal: the authored
+    baseline times whatever XpModifier multiplier is currently active on the
+    character (player-online / player-actively-timing boosts - see
+    gameplay.services.xp_modifiers).
+
+    Deliberately not derived from lifetime AP total - an old character
+    accumulates AP over a long life regardless of whether a player is
+    currently engaged with it, which would read as misleadingly
+    "productive". Reading live modifier state instead gives instant
+    feedback: productivity moves the moment a boost activates or clears, no
+    averaging/smoothing/lag.
+    """
+    return CHARACTER_BASELINE_PRODUCTIVITY * get_multiplier(character, now=now)
diff --git a/progression/tests/test_ap.py b/progression/tests/test_ap.py
index 94f95b40..ca2f803e 100644
--- a/progression/tests/test_ap.py
+++ b/progression/tests/test_ap.py
@@ -140,3 +140,57 @@ def test_works_for_player_scope_too(self):
             is_active=True,
         )
         self.assertEqual(ap.get_multiplier(player, now=self.now), Decimal("1.5"))
+
+
+class GetProductivityTests(TestCase):
+    def setUp(self):
+        self.character = Character.objects.create(given_name="Test")
+        self.now = timezone.now()
+
+    def test_no_modifiers_returns_baseline(self):
+        self.assertEqual(
+            ap.get_productivity(self.character, now=self.now),
+            ap.CHARACTER_BASELINE_PRODUCTIVITY,
+        )
+
+    def test_active_modifier_scales_baseline(self):
+        XpModifier.objects.create(
+            scope=XpModifier.Scope.CHARACTER,
+            character=self.character,
+            key="test_modifier",
+            multiplier=Decimal("1.5"),
+            starts_at=self.now - timedelta(hours=1),
+            is_active=True,
+        )
+        self.assertEqual(
+            ap.get_productivity(self.character, now=self.now),
+            ap.CHARACTER_BASELINE_PRODUCTIVITY * Decimal("1.5"),
+        )
+
+    def test_inactive_modifier_excluded(self):
+        XpModifier.objects.create(
+            scope=XpModifier.Scope.CHARACTER,
+            character=self.character,
+            key="test_modifier",
+            multiplier=Decimal("2"),
+            starts_at=self.now - timedelta(hours=1),
+            is_active=False,
+        )
+        self.assertEqual(
+            ap.get_productivity(self.character, now=self.now),
+            ap.CHARACTER_BASELINE_PRODUCTIVITY,
+        )
+
+    def test_character_get_productivity_matches_ap_function(self):
+        XpModifier.objects.create(
+            scope=XpModifier.Scope.CHARACTER,
+            character=self.character,
+            key="test_modifier",
+            multiplier=Decimal("1.25"),
+            starts_at=self.now - timedelta(hours=1),
+            is_active=True,
+        )
+        self.assertEqual(
+            self.character.get_productivity(now=self.now),
+            ap.get_productivity(self.character, now=self.now),
+        )

From 0cc4123d443bcacbbe8ecb162b097d27aa249bc8 Mon Sep 17 00:00:00 2001
From: Duncan Appleby <duncan@progressrpg.com>
Date: Fri, 14 Aug 2026 10:31:32 +0100
Subject: [PATCH 3/6] feat: story bucket-1 components for Storybook coverage
 (#749)

Adds stories for the pure, prop-driven component gaps identified in #749:
PlayerItemList, List/Li, Achievements, ModeSwitcher, EntitySearchInput,
TutorialModal, WaitlistForm, StaticBanner, BackToTopButton, ToastManager.

Also adds the minimal decorator infra these turned out to need:
- withQueryClient (global): a fresh, retry-off QueryClient per story, for
  components that call TanStack Query hooks directly or transitively
  (EntitySearchInput, TutorialModal both do, despite being listed as
  context-free in the issue's audit).
- withGameContext + testUtils/mockGameContext: a minimal GameContext mock
  for EntitySearchInput's indirect useGame() dependency (via useFeatureFlag).

ActivityInput was left out of this batch - it now pulls in useGame,
useSupportFlow, useFeatureFlag and timer state, which is bucket-2/3-level
complexity, not the "prop-driven, no context" component the issue described.
---
 .../.storybook/decorators/withGameContext.tsx |  14 +++
 .../.storybook/decorators/withQueryClient.tsx |  27 +++++
 frontend/.storybook/preview.tsx               |   6 +
 .../Achievements/Achievements.stories.tsx     |  93 +++++++++++++++
 .../BackToTopButton.stories.tsx               |  24 ++++
 .../EntitySearchInput.stories.tsx             |  87 ++++++++++++++
 frontend/src/components/List/Li.stories.tsx   |  42 +++++++
 frontend/src/components/List/List.stories.tsx |  80 +++++++++++++
 .../ModeSwitcher/ModeSwitcher.stories.tsx     |  45 +++++++
 .../PlayerItemList/PlayerItemList.stories.tsx | 111 ++++++++++++++++++
 .../StaticBanner/StaticBanner.stories.tsx     |  25 ++++
 .../components/Toast/ToastManager.stories.tsx |  52 ++++++++
 .../TutorialModal/TutorialModal.stories.tsx   |  89 ++++++++++++++
 .../WaitlistForm/WaitlistForm.stories.tsx     |  30 +++++
 frontend/src/testUtils/mockGameContext.ts     |  56 +++++++++
 15 files changed, 781 insertions(+)
 create mode 100644 frontend/.storybook/decorators/withGameContext.tsx
 create mode 100644 frontend/.storybook/decorators/withQueryClient.tsx
 create mode 100644 frontend/src/components/Achievements/Achievements.stories.tsx
 create mode 100644 frontend/src/components/BackToTopButton/BackToTopButton.stories.tsx
 create mode 100644 frontend/src/components/EntitySearchInput/EntitySearchInput.stories.tsx
 create mode 100644 frontend/src/components/List/Li.stories.tsx
 create mode 100644 frontend/src/components/List/List.stories.tsx
 create mode 100644 frontend/src/components/ModeSwitcher/ModeSwitcher.stories.tsx
 create mode 100644 frontend/src/components/PlayerItemList/PlayerItemList.stories.tsx
 create mode 100644 frontend/src/components/StaticBanner/StaticBanner.stories.tsx
 create mode 100644 frontend/src/components/Toast/ToastManager.stories.tsx
 create mode 100644 frontend/src/components/TutorialModal/TutorialModal.stories.tsx
 create mode 100644 frontend/src/components/WaitlistForm/WaitlistForm.stories.tsx
 create mode 100644 frontend/src/testUtils/mockGameContext.ts

diff --git a/frontend/.storybook/decorators/withGameContext.tsx b/frontend/.storybook/decorators/withGameContext.tsx
new file mode 100644
index 00000000..97591358
--- /dev/null
+++ b/frontend/.storybook/decorators/withGameContext.tsx
@@ -0,0 +1,14 @@
+import type { Decorator } from '@storybook/react-vite';
+import { GameContext } from '../../src/context/gameContext';
+import { mockGameContextValue } from '../../src/testUtils/mockGameContext';
+
+/**
+ * Wraps a story in `GameContext` with `mockGameContextValue`, for components
+ * that read `useGame()` (directly, or transitively via `useFeatureFlag`)
+ * outside of a real game session.
+ */
+export const withGameContext: Decorator = (Story) => (
+  <GameContext.Provider value={mockGameContextValue}>
+    <Story />
+  </GameContext.Provider>
+);
diff --git a/frontend/.storybook/decorators/withQueryClient.tsx b/frontend/.storybook/decorators/withQueryClient.tsx
new file mode 100644
index 00000000..d18fa097
--- /dev/null
+++ b/frontend/.storybook/decorators/withQueryClient.tsx
@@ -0,0 +1,27 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import type { Decorator } from '@storybook/react-vite';
+
+/**
+ * Wraps a story in a fresh `QueryClient` per render, so components that call
+ * TanStack Query hooks (`useQuery`/`useQueryClient`) don't crash outside a
+ * provider. Retries are disabled - Storybook has no real API to fetch from,
+ * so a failed request should render its empty/error state immediately
+ * rather than retrying for several seconds.
+ *
+ * Seed data for a specific query (so a component renders populated instead
+ * of loading/empty) via a story's own decorator + `queryClient.setQueryData`,
+ * see `EntitySearchInput.stories.tsx` / `TutorialModal.stories.tsx`.
+ */
+export const withQueryClient: Decorator = (Story) => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, staleTime: Infinity },
+    },
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Story />
+    </QueryClientProvider>
+  );
+};
diff --git a/frontend/.storybook/preview.tsx b/frontend/.storybook/preview.tsx
index 797871d2..ab69c54a 100644
--- a/frontend/.storybook/preview.tsx
+++ b/frontend/.storybook/preview.tsx
@@ -1,7 +1,13 @@
 import type { Preview } from '@storybook/react-vite';
 import '../src/styles/main.scss';
+import { withQueryClient } from './decorators/withQueryClient';
 
 const preview: Preview = {
+  // Global so any component that calls a TanStack Query hook - directly or
+  // transitively (e.g. `useFeatureFlag` -> `useAppConfig`) - doesn't crash
+  // for lack of a QueryClientProvider ancestor. See withQueryClient's
+  // comment for how a story seeds its own query data.
+  decorators: [withQueryClient],
   parameters: {
     controls: {
       matchers: {
diff --git a/frontend/src/components/Achievements/Achievements.stories.tsx b/frontend/src/components/Achievements/Achievements.stories.tsx
new file mode 100644
index 00000000..f748ff36
--- /dev/null
+++ b/frontend/src/components/Achievements/Achievements.stories.tsx
@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import Achievements from './Achievements';
+
+/**
+ * `Achievements` renders a grid of achievement badges from a plain
+ * `achievements[]` prop - tier colour, progress bar, and the "time" vs.
+ * count value formatting are all derived from each achievement's fields.
+ */
+const meta: Meta<typeof Achievements> = {
+  title: 'Shared/Achievements',
+  component: Achievements,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Achievements>;
+
+export const Default: Story = {
+  args: {
+    achievements: [
+      {
+        type: 'tasks_completed',
+        label: 'Task Master',
+        symbol: '✅',
+        tier: 1,
+        complete: false,
+        color: 'grey',
+        value: 12,
+        threshold: 25,
+      },
+      {
+        type: 'tasks_completed',
+        label: 'Task Master',
+        symbol: '✅',
+        tier: 2,
+        complete: true,
+        color: 'green',
+        value: 50,
+        threshold: 50,
+      },
+      {
+        type: 'time',
+        label: 'Time Invested',
+        symbol: '⏱️',
+        tier: 3,
+        complete: false,
+        color: 'blue',
+        value: 5400,
+        threshold: 36000,
+      },
+      {
+        type: 'streak',
+        label: 'Consistency',
+        symbol: '🔥',
+        tier: 4,
+        complete: false,
+        color: 'purple',
+        value: 8,
+        threshold: 30,
+      },
+      {
+        type: 'level',
+        label: 'Levelled Up',
+        symbol: '⭐',
+        tier: 5,
+        complete: true,
+        color: 'gold',
+        value: 20,
+        threshold: 20,
+      },
+    ],
+  },
+};
+
+/** Every tier colour Achievements knows about (`grey`/`green`/`blue`/`purple`/`gold`), all mid-progress. */
+export const AllTiers: Story = {
+  args: {
+    achievements: (['grey', 'green', 'blue', 'purple', 'gold'] as const).map((color, i) => ({
+      type: 'tasks_completed',
+      label: `Tier ${i + 1}`,
+      symbol: '🏅',
+      tier: i + 1,
+      complete: false,
+      color,
+      value: (i + 1) * 5,
+      threshold: 50,
+    })),
+  },
+};
+
+export const Empty: Story = {
+  args: { achievements: [] },
+};
diff --git a/frontend/src/components/BackToTopButton/BackToTopButton.stories.tsx b/frontend/src/components/BackToTopButton/BackToTopButton.stories.tsx
new file mode 100644
index 00000000..f6e457c2
--- /dev/null
+++ b/frontend/src/components/BackToTopButton/BackToTopButton.stories.tsx
@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import BackToTopButton from './BackToTopButton';
+
+/**
+ * `BackToTopButton` is a fixed-position button that smooth-scrolls the page
+ * to the top (instantly, if the user prefers reduced motion). No props -
+ * visibility/positioning is left to the page that mounts it.
+ */
+const meta: Meta<typeof BackToTopButton> = {
+  title: 'Shared/BackToTopButton',
+  component: BackToTopButton,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof BackToTopButton>;
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('button', { name: 'Back to top' })).toBeVisible();
+  },
+};
diff --git a/frontend/src/components/EntitySearchInput/EntitySearchInput.stories.tsx b/frontend/src/components/EntitySearchInput/EntitySearchInput.stories.tsx
new file mode 100644
index 00000000..09782d7b
--- /dev/null
+++ b/frontend/src/components/EntitySearchInput/EntitySearchInput.stories.tsx
@@ -0,0 +1,87 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import EntitySearchInput from './EntitySearchInput';
+import { GameContext } from '../../context/gameContext';
+import { mockGameContextValue } from '../../testUtils/mockGameContext';
+
+/**
+ * `EntitySearchInput` is a fuzzy-search combobox over the player's past
+ * activities/tasks (`useEntitySearchCache`, a TanStack Query hook that in
+ * turn calls `useFeatureFlag` -> `useGame()`). The story seeds the cache's
+ * query directly and supplies a mock `GameContext` so it renders without a
+ * real API or game session - see `.storybook/decorators/`.
+ */
+const entities = [
+  { id: 'a1', name: 'Wash dishes', taskId: null, completedAt: null, source: 'activity', isOptimistic: false, frequency: 4 },
+  { id: 'a2', name: 'Write report', taskId: null, completedAt: null, source: 'activity', isOptimistic: false, frequency: 2 },
+  { id: 't1', name: 'Write tests', taskId: 12, completedAt: null, source: 'task', isOptimistic: false, frequency: 0 },
+];
+
+function withSeededCache(Story: () => React.ReactElement) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  queryClient.setQueryData(['entity-search', 'activity'], entities);
+  queryClient.setQueryData(['appConfig'], { feature_flags: {} });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <GameContext.Provider value={mockGameContextValue}>
+        <Story />
+      </GameContext.Provider>
+    </QueryClientProvider>
+  );
+}
+
+const meta: Meta<typeof EntitySearchInput> = {
+  title: 'Shared/EntitySearchInput',
+  component: EntitySearchInput,
+  tags: ['autodocs'],
+  decorators: [withSeededCache],
+  args: {
+    type: 'activity',
+    ariaLabel: 'Activity name',
+    placeholder: 'What are you working on?',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof EntitySearchInput>;
+
+function ControlledInput(props: Partial<React.ComponentProps<typeof EntitySearchInput>>) {
+  const [value, setValue] = useState(props.value ?? '');
+  return <EntitySearchInput {...(props as React.ComponentProps<typeof EntitySearchInput>)} value={value} onChange={setValue} />;
+}
+
+export const Default: Story = {
+  render: (args) => <ControlledInput {...args} />,
+};
+
+/** Typing surfaces matching activities/tasks in a dropdown, grouped by source when both are present. */
+export const WithSuggestions: Story = {
+  render: (args) => <ControlledInput {...args} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.type(canvas.getByRole('combobox'), 'write');
+
+    await waitFor(async () => {
+      await expect(canvas.getByRole('listbox')).toBeVisible();
+    });
+    await expect(canvas.getByRole('option', { name: 'Write tests' })).toBeVisible();
+    await expect(canvas.getByRole('option', { name: 'Write report' })).toBeVisible();
+  },
+};
+
+/** `alwaysOpen` keeps the dropdown mounted regardless of focus (persistent list mode), falling back to `emptyMessage` when there are no rows. */
+export const AlwaysOpenEmpty: Story = {
+  args: {
+    alwaysOpen: true,
+    emptyMessage: 'No recent activities yet.',
+    defaultResults: [],
+  },
+  render: (args) => <ControlledInput {...args} />,
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, value: 'Timer running...' },
+};
diff --git a/frontend/src/components/List/Li.stories.tsx b/frontend/src/components/List/Li.stories.tsx
new file mode 100644
index 00000000..630d6733
--- /dev/null
+++ b/frontend/src/components/List/Li.stories.tsx
@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import Li from './Li';
+
+/**
+ * `Li` is the single-row primitive `List` maps over. Storied directly for
+ * its own states (`isSelected`, `isHidden`, `tone`) - `List`'s stories cover
+ * it in context, as a full `<ul>`.
+ */
+const meta: Meta<typeof Li> = {
+  title: 'Shared/List/Li',
+  component: Li,
+  tags: ['autodocs'],
+  render: (args) => (
+    <ul>
+      <Li {...args} />
+    </ul>
+  ),
+  args: {
+    children: 'Row content',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Li>;
+
+export const Default: Story = {};
+
+export const Selected: Story = {
+  args: { isSelected: true },
+};
+
+export const Hidden: Story = {
+  args: { isHidden: true },
+};
+
+export const PlayerTone: Story = {
+  args: { tone: 'player', children: 'You finished Write docs' },
+};
+
+export const CharacterTone: Story = {
+  args: { tone: 'character', children: 'Rosie finished Deliver goods' },
+};
diff --git a/frontend/src/components/List/List.stories.tsx b/frontend/src/components/List/List.stories.tsx
new file mode 100644
index 00000000..6ab23145
--- /dev/null
+++ b/frontend/src/components/List/List.stories.tsx
@@ -0,0 +1,80 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent } from 'storybook/test';
+import List from './List';
+
+/**
+ * `List` renders a `<ul>` of `Li` rows and underlies `PlayerItemList` (which
+ * adds sort/filter/edit-modal behaviour on top). On its own it handles
+ * selection, hover/compact styling, and per-item tone (e.g. distinguishing
+ * player vs. character rows in an activity feed).
+ */
+interface DemoItem {
+  id: string;
+  name: string;
+  player?: unknown;
+  character?: unknown;
+  isHidden?: boolean;
+}
+
+const items: DemoItem[] = [
+  { id: '1', name: 'Alice' },
+  { id: '2', name: 'Bob' },
+  { id: '3', name: 'Carol' },
+];
+
+const meta: Meta<typeof List<DemoItem>> = {
+  title: 'Shared/List',
+  component: List,
+  tags: ['autodocs'],
+  args: {
+    items,
+    ariaLabel: 'Names',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof List<DemoItem>>;
+
+export const Default: Story = {};
+
+export const CanHover: Story = {
+  args: { canHover: true },
+};
+
+export const Compact: Story = {
+  args: { compact: true },
+};
+
+/** A hidden item (e.g. a deep-link placeholder) stays in the DOM but is visually suppressed via `isHidden`. */
+export const WithHiddenItem: Story = {
+  args: {
+    items: [...items, { id: '4', name: 'Dave', isHidden: true }],
+  },
+};
+
+/** `itemTone`/`getItemTone` colour rows by origin - e.g. an activity feed mixing player and character entries. */
+export const MixedTone: Story = {
+  args: {
+    items: [
+      { id: '1', name: 'You finished Write docs', player: {} },
+      { id: '2', name: 'Rosie finished Deliver goods', character: {} },
+    ],
+  },
+};
+
+/** `canSelect` renders a `listbox`/`option` pair with keyboard (Enter/Space) activation instead of a plain list. */
+export const Selectable: Story = {
+  render: (args) => {
+    function Wrapper() {
+      const [selectedItem, setSelectedItem] = useState<DemoItem | null>(null);
+      return <List {...args} selectedItem={selectedItem} onSelect={setSelectedItem} canSelect />;
+    }
+    return <Wrapper />;
+  },
+  play: async ({ canvas }) => {
+    const option = canvas.getByRole('option', { name: 'Bob' });
+    await userEvent.click(option);
+    await expect(option).toHaveAttribute('aria-selected', 'true');
+  },
+};
diff --git a/frontend/src/components/ModeSwitcher/ModeSwitcher.stories.tsx b/frontend/src/components/ModeSwitcher/ModeSwitcher.stories.tsx
new file mode 100644
index 00000000..bcca2700
--- /dev/null
+++ b/frontend/src/components/ModeSwitcher/ModeSwitcher.stories.tsx
@@ -0,0 +1,45 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent } from 'storybook/test';
+import ModeSwitcher from './ModeSwitcher';
+import type { ModeOption } from './ModeSwitcher';
+
+/**
+ * `ModeSwitcher` is a `radiogroup` of chips (e.g. Tasks/Activities panel
+ * mode). Fully generic over `modes`/`activeKey`/`onSelect`; arrow keys move
+ * (and select) between options, Home/End jump to the first/last.
+ */
+const modes: ModeOption[] = [
+  { key: 'tasks', label: 'Tasks' },
+  { key: 'activities', label: 'Activities' },
+  { key: 'skills', label: 'Skills' },
+];
+
+const meta: Meta<typeof ModeSwitcher> = {
+  title: 'Shared/ModeSwitcher',
+  component: ModeSwitcher,
+  tags: ['autodocs'],
+  args: {
+    modes,
+    activeKey: 'tasks',
+    ariaLabel: 'View mode',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ModeSwitcher>;
+
+export const Default: Story = {
+  render: (args) => {
+    function Wrapper() {
+      const [activeKey, setActiveKey] = useState(args.activeKey);
+      return <ModeSwitcher {...args} activeKey={activeKey} onSelect={setActiveKey} />;
+    }
+    return <Wrapper />;
+  },
+  play: async ({ canvas }) => {
+    const activities = canvas.getByRole('radio', { name: 'Activities' });
+    await userEvent.click(activities);
+    await expect(activities).toHaveAttribute('aria-checked', 'true');
+  },
+};
diff --git a/frontend/src/components/PlayerItemList/PlayerItemList.stories.tsx b/frontend/src/components/PlayerItemList/PlayerItemList.stories.tsx
new file mode 100644
index 00000000..a4edf20b
--- /dev/null
+++ b/frontend/src/components/PlayerItemList/PlayerItemList.stories.tsx
@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
+import PlayerItemList from './PlayerItemList';
+import type { FilterOption, SortOption } from './PlayerItemList';
+
+/**
+ * `PlayerItemList` is the generic, prop-driven list underlying
+ * `CategoriesPanel`, `ProjectsPanel`, `SkillsPanel`, `TasksPanel`, and
+ * `ActivitiesPanel` - it owns sorting, filtering, the edit/delete modal,
+ * hover-edit affordances, and nested children, while the panel supplies the
+ * item shape and callbacks. Storying it here documents most of what those
+ * five panels visually do.
+ */
+interface DemoItem {
+  id: number;
+  name: string;
+  detail: string;
+  complete?: boolean;
+}
+
+const items: DemoItem[] = [
+  { id: 1, name: 'Write docs', detail: 'Duration: 15m · 15 XP gained', complete: false },
+  { id: 2, name: 'Fix login bug', detail: 'Duration: 42m · 40 XP gained', complete: true },
+  { id: 3, name: 'Plan sprint', detail: 'Duration: 5m · 5 XP gained', complete: false },
+];
+
+const sortOptions: SortOption<DemoItem>[] = [
+  { key: 'name', label: 'Name', compareFn: (a, b) => a.name.localeCompare(b.name) },
+  { key: 'newest', label: 'Newest', compareFn: (a, b) => b.id - a.id },
+];
+
+const filterOptions: FilterOption<DemoItem>[] = [
+  { key: 'all', label: 'All', predicate: () => true },
+  { key: 'incomplete', label: 'Incomplete', predicate: (item) => !item.complete },
+];
+
+const meta: Meta<typeof PlayerItemList<DemoItem>> = {
+  title: 'Shared/PlayerItemList',
+  component: PlayerItemList,
+  tags: ['autodocs'],
+  args: {
+    items,
+    itemLabel: 'activity',
+    ariaLabel: 'Activities',
+    renderItemMeta: (item: DemoItem) => item.detail,
+    onEdit: () => {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PlayerItemList<DemoItem>>;
+
+export const Default: Story = {};
+
+/** `hoverEdit` swaps the row's click-to-open button for a persistent detail area plus a hover-revealed edit icon - used by panels where the row itself does something else on click. */
+export const HoverEdit: Story = {
+  args: { hoverEdit: true },
+};
+
+/** `isItemComplete`/`onToggleComplete` add a per-row checkbox, e.g. for `TasksPanel`. */
+export const WithCompleteToggle: Story = {
+  args: {
+    isItemComplete: (item: DemoItem) => Boolean(item.complete),
+    onToggleComplete: () => {},
+  },
+};
+
+/** `sortOptions`/`filterOptions` render a controls bar above the list. */
+export const WithSortAndFilter: Story = {
+  args: { sortOptions, filterOptions },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByRole('group', { name: 'Filter activitys' })).toBeVisible();
+    await expect(canvas.getByLabelText('Sort:')).toBeVisible();
+  },
+};
+
+/** `getChildren` nests an item's children directly under it (e.g. subtasks), independent of the active sort/filter. */
+export const WithNestedChildren: Story = {
+  args: {
+    items: [
+      { id: 1, name: 'Ship v1', detail: '2 subtasks', complete: false },
+      { id: 2, name: 'Write changelog', detail: 'Duration: 10m', complete: false },
+      { id: 3, name: 'Cut release', detail: 'Duration: 5m', complete: true },
+    ],
+    getChildren: (item: DemoItem) =>
+      item.id === 1
+        ? [
+            { id: 2, name: 'Write changelog', detail: 'Duration: 10m', complete: false },
+            { id: 3, name: 'Cut release', detail: 'Duration: 5m', complete: true },
+          ]
+        : undefined,
+  },
+};
+
+/** No items - the shared empty list state (an empty `<ul>`, no placeholder copy of its own). */
+export const Empty: Story = {
+  args: { items: [] },
+};
+
+/** Clicking a row opens the edit modal; `onDelete` adds a Delete action with its own confirm step. */
+export const EditModal: Story = {
+  args: { onDelete: () => {} },
+  play: async ({ canvasElement, canvas }) => {
+    await userEvent.click(canvas.getByRole('button', { name: 'Open activity Write docs' }));
+
+    const body = within(canvasElement.ownerDocument.body);
+    const dialog = await body.findByRole('dialog', { name: 'Edit activity' });
+    await expect(dialog).toBeVisible();
+    await expect(body.getByRole('button', { name: 'Delete' })).toBeVisible();
+  },
+};
diff --git a/frontend/src/components/StaticBanner/StaticBanner.stories.tsx b/frontend/src/components/StaticBanner/StaticBanner.stories.tsx
new file mode 100644
index 00000000..96e31d40
--- /dev/null
+++ b/frontend/src/components/StaticBanner/StaticBanner.stories.tsx
@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import StaticBanner from './StaticBanner';
+
+/**
+ * `StaticBanner` is a single-line site announcement. It renders nothing
+ * when `message` is empty/unset, so a running app with no announcement
+ * configured shows no banner at all.
+ */
+const meta: Meta<typeof StaticBanner> = {
+  title: 'Shared/StaticBanner',
+  component: StaticBanner,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof StaticBanner>;
+
+export const Default: Story = {
+  args: { message: "Scheduled maintenance tonight at 10pm UTC - the app may be briefly unavailable." },
+};
+
+/** No `message` - renders nothing. */
+export const NoMessage: Story = {
+  args: {},
+};
diff --git a/frontend/src/components/Toast/ToastManager.stories.tsx b/frontend/src/components/Toast/ToastManager.stories.tsx
new file mode 100644
index 00000000..e7b4f8d9
--- /dev/null
+++ b/frontend/src/components/Toast/ToastManager.stories.tsx
@@ -0,0 +1,52 @@
+import * as RadixToast from '@radix-ui/react-toast';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import ToastManager from './ToastManager';
+
+/**
+ * `ToastManager` renders a `messages[]` prop as Radix `Toast.Root`s plus the
+ * shared `Toast.Viewport`. It must be mounted under a Radix `Toast.Provider`
+ * (normally supplied by `ToastContext`) - the story provides one directly.
+ */
+const meta: Meta<typeof ToastManager> = {
+  title: 'Shared/ToastManager',
+  component: ToastManager,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <RadixToast.Provider>
+        <Story />
+      </RadixToast.Provider>
+    ),
+  ],
+  args: {
+    onDismiss: () => {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ToastManager>;
+
+export const Default: Story = {
+  args: {
+    messages: [{ id: '1', message: 'Task saved.' }],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Task saved.')).toBeVisible();
+  },
+};
+
+export const Multiple: Story = {
+  args: {
+    messages: [
+      { id: '1', message: 'Task saved.' },
+      { id: '2', message: 'Activity logged - 15 XP gained.' },
+      { id: '3', message: 'Level up! You reached level 6.' },
+    ],
+  },
+};
+
+export const Empty: Story = {
+  args: { messages: [] },
+};
diff --git a/frontend/src/components/TutorialModal/TutorialModal.stories.tsx b/frontend/src/components/TutorialModal/TutorialModal.stories.tsx
new file mode 100644
index 00000000..f275d946
--- /dev/null
+++ b/frontend/src/components/TutorialModal/TutorialModal.stories.tsx
@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { expect, within } from 'storybook/test';
+import TutorialModal from './TutorialModal';
+import type { TutorialStep } from '../../types';
+
+/**
+ * `TutorialModal` walks through `TutorialStep`s fetched via `useTutorialSteps`
+ * (a TanStack Query hook - see `withQueryClient` in `.storybook/preview.tsx`).
+ * Each story seeds the `["tutorial-steps"]` query directly with
+ * `queryClient.setQueryData` so the modal renders without a real API call.
+ */
+const steps: TutorialStep[] = [
+  {
+    id: 1,
+    order: 1,
+    title: 'Welcome to Progress RPG',
+    body: 'Your character levels up as you complete real-world tasks and activities.',
+    image_url: null,
+    alt_text: '',
+    youtube_url: null,
+  },
+  {
+    id: 2,
+    order: 2,
+    title: 'Start a timer',
+    body: 'Type what you\'re working on and hit Start - XP accrues while the timer runs.',
+    image_url: null,
+    alt_text: '',
+    youtube_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+  },
+  {
+    id: 3,
+    order: 3,
+    title: "You're all set",
+    body: 'That\'s the core loop. Explore the map to see other characters at work.',
+    image_url: null,
+    alt_text: '',
+    youtube_url: null,
+  },
+];
+
+/** Seeds `["tutorial-steps"]` with `data` before the story renders. */
+function withSeededSteps(data: TutorialStep[]) {
+  return (Story: () => React.ReactElement) => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(['tutorial-steps'], data);
+    return (
+      <QueryClientProvider client={queryClient}>
+        <Story />
+      </QueryClientProvider>
+    );
+  };
+}
+
+const meta: Meta<typeof TutorialModal> = {
+  title: 'Shared/TutorialModal',
+  component: TutorialModal,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      story: { inline: false, iframeHeight: 420 },
+    },
+  },
+  args: {
+    onClose: () => {},
+  },
+  decorators: [withSeededSteps(steps)],
+};
+
+export default meta;
+type Story = StoryObj<typeof TutorialModal>;
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const body = within(canvasElement.ownerDocument.body);
+    await expect(await body.findByRole('dialog', { name: 'Welcome to Progress RPG' })).toBeVisible();
+    await expect(body.getByText('1 / 3')).toBeVisible();
+  },
+};
+
+/** `startAtStepId` opens directly on a later step, e.g. re-opening from a "Learn more" link elsewhere in the app. */
+export const StartAtLaterStep: Story = {
+  args: { startAtStepId: 2 },
+};
+
+export const NoSteps: Story = {
+  decorators: [withSeededSteps([])],
+};
diff --git a/frontend/src/components/WaitlistForm/WaitlistForm.stories.tsx b/frontend/src/components/WaitlistForm/WaitlistForm.stories.tsx
new file mode 100644
index 00000000..71c9bb47
--- /dev/null
+++ b/frontend/src/components/WaitlistForm/WaitlistForm.stories.tsx
@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import WaitlistForm from './WaitlistForm';
+
+/**
+ * `WaitlistForm` is a single-field email form backed by `useWaitlistJoin`,
+ * which posts to the real waitlist API - the story only exercises the idle,
+ * pre-submission render (an interactive Storybook play test would hit a
+ * live endpoint).
+ */
+const meta: Meta<typeof WaitlistForm> = {
+  title: 'Shared/WaitlistForm',
+  component: WaitlistForm,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof WaitlistForm>;
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('heading', { name: 'Join the Waitlist' })).toBeVisible();
+    await expect(canvas.getByLabelText('Email:')).toBeVisible();
+  },
+};
+
+export const CustomTitle: Story = {
+  args: { title: 'Be first in line' },
+};
diff --git a/frontend/src/testUtils/mockGameContext.ts b/frontend/src/testUtils/mockGameContext.ts
new file mode 100644
index 00000000..f591ce9a
--- /dev/null
+++ b/frontend/src/testUtils/mockGameContext.ts
@@ -0,0 +1,56 @@
+import type { GameContextValue } from '../context/gameContext';
+
+/**
+ * Minimal `GameContextValue` covering only what story-ready components
+ * actually read (currently `player`, via `useFeatureFlag`). The rest are
+ * stubs so the object satisfies the full interface without pulling in
+ * `GameProvider`'s real bootstrap/fetch logic - extend as more components
+ * that read other fields get storied.
+ *
+ * Used by Storybook stories that mount `GameContext.Provider` directly
+ * (`.storybook/decorators/withGameContext.tsx`, `EntitySearchInput.stories.tsx`).
+ */
+export const mockGameContextValue: GameContextValue = {
+  player: null,
+  setPlayer: () => {},
+  character: null,
+  setCharacter: () => {},
+  xpMods: [],
+  setXpMods: () => {},
+  fetchPlayerAndCharacter: async () => {},
+  activityTimer: {
+    status: 'empty',
+    elapsed: 0,
+    duration: 0,
+    limitSeconds: null,
+    limitReached: false,
+    autoStopCompletion: null,
+    currentActivity: null,
+    startActivity: async () => null,
+    labelActivity: async () => null,
+    stop: async () => null,
+    loadFromServer: () => {},
+    clearAutoStopCompletion: () => {},
+  },
+  playerActivities: [],
+  characterActivities: [],
+  fetchActivities: async () => {},
+  fetchCharacterCurrent: async () => null,
+  characterCurrentActivity: null,
+  setCharacterCurrentActivity: () => {},
+  populationCentre: null,
+  fetchPopulationCentre: async () => {
+    throw new Error('fetchPopulationCentre is not mocked in Storybook');
+  },
+  loginState: 'none',
+  loginStreak: 0,
+  loginEventAt: null,
+  loginRewardXp: 0,
+  announcementUnreadCount: 0,
+  setAnnouncementUnreadCount: () => {},
+  loading: false,
+  buildNumber: false,
+  freeTimerLimitSeconds: 1800,
+  gameSettings: null,
+  initialOnlineCount: 0,
+};

From 13e7d374c5712061a728f4bb756dd3eb085aa377 Mon Sep 17 00:00:00 2001
From: Duncan Appleby <duncan@progressrpg.com>
Date: Fri, 14 Aug 2026 10:52:10 +0100
Subject: [PATCH 4/6] feat: story layout chrome for Storybook coverage (#749)

Stories Navbar, NavDrawer, Footer, and Infobar - the layout chrome
called out as bucket 3 in #749, step 4 of its suggested approach.

- Split AuthContext's raw context into context/authContext.ts,
  mirroring the existing GameContext.tsx/gameContext.ts split, so it
  can be mounted directly in stories without pulling in AuthProvider's
  real bootstrap/fetch logic.
- Add testUtils/mockAuthContext.ts (mockAuthContextValue({authenticated,
  ...overrides})) and .storybook/decorators/withAuthContext.tsx,
  following bucket-1's conventions.
- Navbar.stories.tsx: LoggedOut, LoggedIn, WithAnnouncements (play test
  opens the popover), WithMapEnabled - wrapped in MemoryRouter + a
  seeded QueryClient (appConfig, announcements) + mock
  AuthContext/GameContext.
- NavDrawer.stories.tsx: LoggedIn (play test clicks close, asserts
  onClose fires), LoggedOut, WithMapEnabled, Closed.
- Footer.stories.tsx: LoggedOut (play test asserts no Admin Panel
  link), LoggedIn, StaffUser (play test asserts the link appears).
- Infobar.stories.tsx: Default (play test asserts name/level),
  PremiumPlayer, Loading, NoPlayer (renders null).

Verified via eslint, tsc --noEmit, and storybook build (all clean),
plus vitest on AuthContext.test.tsx and the Navbar/NavDrawer unit
tests (24 passing) to confirm the context split didn't break anything.
test:storybook (Playwright-driven play functions/a11y) still can't run
in this sandbox - no sudo for Chromium's system deps - run
locally/CI before merging.

Remaining gap per #749: bucket 2 (data-fetching panels - Categories/
Projects/Skills/Tasks/ActivitiesPanel, ComingSoonPanel, NotesPanel,
DetailSurface, SupportFlow screens, UnifiedTimerHome, ActivityTimeline,
CurrentActivity, CharacterCurrentActivity) and the deferred
ActivityInput. Per the issue's own plan, step 5 is to revisit whether
those need separate stories given PlayerItemList's existing coverage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../.storybook/decorators/withAuthContext.tsx |  19 +++
 frontend/src/context/AuthContext.tsx          |  28 +----
 frontend/src/context/authContext.ts           |  19 +++
 frontend/src/layout/Footer/Footer.stories.tsx |  56 +++++++++
 .../src/layout/Infobar/Infobar.stories.tsx    |  74 ++++++++++++
 .../layout/NavDrawer/NavDrawer.stories.tsx    |  83 +++++++++++++
 frontend/src/layout/Navbar/Navbar.stories.tsx | 109 ++++++++++++++++++
 frontend/src/testUtils/mockAuthContext.ts     |  40 +++++++
 8 files changed, 403 insertions(+), 25 deletions(-)
 create mode 100644 frontend/.storybook/decorators/withAuthContext.tsx
 create mode 100644 frontend/src/context/authContext.ts
 create mode 100644 frontend/src/layout/Footer/Footer.stories.tsx
 create mode 100644 frontend/src/layout/Infobar/Infobar.stories.tsx
 create mode 100644 frontend/src/layout/NavDrawer/NavDrawer.stories.tsx
 create mode 100644 frontend/src/layout/Navbar/Navbar.stories.tsx
 create mode 100644 frontend/src/testUtils/mockAuthContext.ts

diff --git a/frontend/.storybook/decorators/withAuthContext.tsx b/frontend/.storybook/decorators/withAuthContext.tsx
new file mode 100644
index 00000000..9420aa0b
--- /dev/null
+++ b/frontend/.storybook/decorators/withAuthContext.tsx
@@ -0,0 +1,19 @@
+import type { Decorator } from '@storybook/react-vite';
+import { AuthContext, type AuthContextValue } from '../../src/context/authContext';
+import { mockAuthContextValue } from '../../src/testUtils/mockAuthContext';
+
+/**
+ * Wraps a story in `AuthContext` with a mock value, for components that read
+ * `useAuth()` outside of a real session. `authenticated` controls whether the
+ * mock represents a logged-in or logged-out user; `overrides` reaches any
+ * other field (e.g. `user: { is_staff: true }`).
+ */
+export function withAuthContext(
+  overrides: Partial<AuthContextValue> & { authenticated?: boolean } = {}
+): Decorator {
+  return (Story) => (
+    <AuthContext.Provider value={mockAuthContextValue(overrides)}>
+      <Story />
+    </AuthContext.Provider>
+  );
+}
diff --git a/frontend/src/context/AuthContext.tsx b/frontend/src/context/AuthContext.tsx
index 8c04e3ce..4b586aa6 100644
--- a/frontend/src/context/AuthContext.tsx
+++ b/frontend/src/context/AuthContext.tsx
@@ -1,37 +1,15 @@
-import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
-import type { Dispatch, ReactElement, ReactNode, SetStateAction } from 'react';
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import { apiFetch, ApiFetchError, setUnauthorizedHandler } from "../utils/api";
 import { clearAuthStorage, getStoredAuthTokens, storeAuthTokens } from '../utils/authStorage';
 import { clearUserPreferences } from '../utils/userPreferences';
+import { AuthContext, type AuthContextValue } from './authContext';
 import type { User } from '../types';
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface AuthContextValue {
-  accessToken: string | null;
-  refreshToken: string | null;
-  isAuthenticated: boolean;
-  user: User | null;
-  setUser: Dispatch<SetStateAction<User | null>>;
-  login: (accessToken: string, refreshToken: string, options?: { rememberMe?: boolean }) => Promise<unknown>;
-  logout: () => void;
-  /** Thin wrapper around apiFetch — use apiFetch directly for typed responses. */
-  authFetch: <T = unknown>(path: string, options?: Parameters<typeof apiFetch>[1]) => Promise<T>;
-  loading: boolean;
-}
-
 interface ProviderProps {
   children: ReactNode;
 }
 
-// ---------------------------------------------------------------------------
-// Context
-// ---------------------------------------------------------------------------
-
-const AuthContext = createContext<AuthContextValue | null>(null);
-
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
diff --git a/frontend/src/context/authContext.ts b/frontend/src/context/authContext.ts
new file mode 100644
index 00000000..2082bd65
--- /dev/null
+++ b/frontend/src/context/authContext.ts
@@ -0,0 +1,19 @@
+import { createContext } from 'react';
+import type { Dispatch, SetStateAction } from 'react';
+import type { apiFetch } from '../utils/api';
+import type { User } from '../types';
+
+export interface AuthContextValue {
+  accessToken: string | null;
+  refreshToken: string | null;
+  isAuthenticated: boolean;
+  user: User | null;
+  setUser: Dispatch<SetStateAction<User | null>>;
+  login: (accessToken: string, refreshToken: string, options?: { rememberMe?: boolean }) => Promise<unknown>;
+  logout: () => void;
+  /** Thin wrapper around apiFetch — use apiFetch directly for typed responses. */
+  authFetch: <T = unknown>(path: string, options?: Parameters<typeof apiFetch>[1]) => Promise<T>;
+  loading: boolean;
+}
+
+export const AuthContext = createContext<AuthContextValue | null>(null);
diff --git a/frontend/src/layout/Footer/Footer.stories.tsx b/frontend/src/layout/Footer/Footer.stories.tsx
new file mode 100644
index 00000000..ffbe5755
--- /dev/null
+++ b/frontend/src/layout/Footer/Footer.stories.tsx
@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MemoryRouter } from 'react-router';
+import { expect, within } from 'storybook/test';
+import Footer from './Footer';
+import { AuthContext } from '../../context/authContext';
+import { mockAuthContextValue } from '../../testUtils/mockAuthContext';
+
+/**
+ * `Footer` reads `useAuth()` only, to gate the "Admin Panel" link behind a
+ * staff user. Wrapped in `MemoryRouter` since its internal links use
+ * `react-router`'s `Link`.
+ */
+function withAuth(overrides: Parameters<typeof mockAuthContextValue>[0] = {}) {
+  return (Story: () => React.ReactElement) => (
+    <MemoryRouter>
+      <AuthContext.Provider value={mockAuthContextValue(overrides)}>
+        <Story />
+      </AuthContext.Provider>
+    </MemoryRouter>
+  );
+}
+
+const meta: Meta<typeof Footer> = {
+  title: 'Layout/Footer',
+  component: Footer,
+  tags: ['autodocs'],
+  decorators: [withAuth()],
+};
+
+export default meta;
+type Story = StoryObj<typeof Footer>;
+
+export const LoggedOut: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('link', { name: 'Support' })).toBeVisible();
+    await expect(canvas.queryByRole('link', { name: 'Admin Panel' })).not.toBeInTheDocument();
+  },
+};
+
+export const LoggedIn: Story = {
+  decorators: [withAuth({ authenticated: true })],
+};
+
+export const StaffUser: Story = {
+  decorators: [
+    withAuth({
+      authenticated: true,
+      user: { email: 'staff@example.com', is_confirmed: true, is_staff: true, is_superuser: false, date_of_birth: null, timezone: 'UTC' },
+    }),
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('link', { name: 'Admin Panel' })).toBeVisible();
+  },
+};
diff --git a/frontend/src/layout/Infobar/Infobar.stories.tsx b/frontend/src/layout/Infobar/Infobar.stories.tsx
new file mode 100644
index 00000000..86a3e1b5
--- /dev/null
+++ b/frontend/src/layout/Infobar/Infobar.stories.tsx
@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import Infobar from './Infobar';
+import { GameContext } from '../../context/gameContext';
+import { mockGameContextValue } from '../../testUtils/mockGameContext';
+import type { Player } from '../../types';
+
+/**
+ * `Infobar` reads `player`/`loading` off `useGame()` - see
+ * `.storybook/decorators/withGameContext.tsx` for the shared mock, extended
+ * here per story with a concrete `player`.
+ */
+const demoPlayer: Player = {
+  id: 1,
+  name: 'Alex',
+  xp: 340,
+  xp_next_level: 500,
+  xp_modifier: 1,
+  level: 7,
+  total_time: 54000,
+  total_activities: 42,
+  achievements: [
+    { type: 'tasks_completed', label: 'Task Master', symbol: '✅', tier: 2, complete: true, color: 'green', value: 50, threshold: 50 },
+    { type: 'streak', label: 'Consistency', symbol: '🔥', tier: 1, complete: false, color: 'grey', value: 8, threshold: 30 },
+  ],
+  is_premium: false,
+  is_tester: false,
+  has_previous_subscription: false,
+  is_trialing: false,
+  trial_end: null,
+  onboarding_step: 5,
+  onboarding_completed: true,
+  login_streak: 8,
+  unseen_tutorial_step_ids: [],
+};
+
+function withPlayer(player: Player | null, loading = false) {
+  return (Story: () => React.ReactElement) => (
+    <GameContext.Provider value={{ ...mockGameContextValue, player, loading }}>
+      <Story />
+    </GameContext.Provider>
+  );
+}
+
+const meta: Meta<typeof Infobar> = {
+  title: 'Layout/Infobar',
+  component: Infobar,
+  tags: ['autodocs'],
+  decorators: [withPlayer(demoPlayer)],
+};
+
+export default meta;
+type Story = StoryObj<typeof Infobar>;
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Alex')).toBeVisible();
+    await expect(canvas.getByText('Level 7')).toBeVisible();
+  },
+};
+
+export const PremiumPlayer: Story = {
+  decorators: [withPlayer({ ...demoPlayer, is_premium: true })],
+};
+
+export const Loading: Story = {
+  decorators: [withPlayer(null, true)],
+};
+
+/** Renders nothing once loaded without a player (e.g. between logout and redirect). */
+export const NoPlayer: Story = {
+  decorators: [withPlayer(null, false)],
+};
diff --git a/frontend/src/layout/NavDrawer/NavDrawer.stories.tsx b/frontend/src/layout/NavDrawer/NavDrawer.stories.tsx
new file mode 100644
index 00000000..c29e0130
--- /dev/null
+++ b/frontend/src/layout/NavDrawer/NavDrawer.stories.tsx
@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MemoryRouter } from 'react-router';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import NavDrawer from './NavDrawer';
+import { AuthContext } from '../../context/authContext';
+import { GameContext } from '../../context/gameContext';
+import { mockAuthContextValue } from '../../testUtils/mockAuthContext';
+import { mockGameContextValue } from '../../testUtils/mockGameContext';
+
+/**
+ * `NavDrawer` is the mobile side-nav - it reads `useAuth()` for which links
+ * to show and `useFeatureFlag("map")` (via a seeded `["appConfig"]` query,
+ * see `useFeatureFlag.ts`) to gate the Map link. Rendered inline via
+ * `parameters.docs.story` since it's a fixed-position overlay, not
+ * document-flow content.
+ */
+function withNavDrawerContext({
+  authenticated = true,
+  featureFlags = {},
+}: {
+  authenticated?: boolean;
+  featureFlags?: Record<string, unknown>;
+}) {
+  return (Story: () => React.ReactElement) => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(['appConfig'], { feature_flags: featureFlags });
+
+    return (
+      <MemoryRouter>
+        <QueryClientProvider client={queryClient}>
+          <AuthContext.Provider value={mockAuthContextValue({ authenticated })}>
+            <GameContext.Provider value={mockGameContextValue}>
+              <Story />
+            </GameContext.Provider>
+          </AuthContext.Provider>
+        </QueryClientProvider>
+      </MemoryRouter>
+    );
+  };
+}
+
+const meta: Meta<typeof NavDrawer> = {
+  title: 'Layout/NavDrawer',
+  component: NavDrawer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      story: { inline: true, iframeHeight: 360 },
+    },
+  },
+  args: {
+    drawerOpen: true,
+    onClose: fn(),
+  },
+  decorators: [withNavDrawerContext({})],
+};
+
+export default meta;
+type Story = StoryObj<typeof NavDrawer>;
+
+export const LoggedIn: Story = {
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('link', { name: /Timer/ })).toBeVisible();
+
+    await userEvent.click(canvas.getByRole('button', { name: 'Close navigation drawer' }));
+    await expect(args.onClose).toHaveBeenCalled();
+  },
+};
+
+export const LoggedOut: Story = {
+  decorators: [withNavDrawerContext({ authenticated: false })],
+};
+
+/** `map` is `["testers"]`-gated by default - enabling it here mirrors a tester/premium account. */
+export const WithMapEnabled: Story = {
+  decorators: [withNavDrawerContext({ featureFlags: { map: 'all' } })],
+};
+
+export const Closed: Story = {
+  args: { drawerOpen: false },
+};
diff --git a/frontend/src/layout/Navbar/Navbar.stories.tsx b/frontend/src/layout/Navbar/Navbar.stories.tsx
new file mode 100644
index 00000000..a5f5584f
--- /dev/null
+++ b/frontend/src/layout/Navbar/Navbar.stories.tsx
@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MemoryRouter } from 'react-router';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import Navbar from './Navbar';
+import { AuthContext } from '../../context/authContext';
+import { GameContext } from '../../context/gameContext';
+import { mockAuthContextValue } from '../../testUtils/mockAuthContext';
+import { mockGameContextValue } from '../../testUtils/mockGameContext';
+import type { AnnouncementListResponse } from '../../types';
+
+/**
+ * `Navbar` reads `useAuth()` (nav links), `useGame()` (unread-announcement
+ * badge) and two `useFeatureFlag()` checks (`map`, `announcements`) that
+ * resolve via a seeded `["appConfig"]` query - see `useFeatureFlag.ts`. Each
+ * story seeds its own `QueryClient` and wraps in `MemoryRouter` since
+ * `Navbar` reads the current route to highlight the active link.
+ */
+function withNavbarContext({
+  authenticated = true,
+  path = '/timer',
+  featureFlags = {},
+  announcements,
+}: {
+  authenticated?: boolean;
+  path?: string;
+  featureFlags?: Record<string, unknown>;
+  announcements?: AnnouncementListResponse;
+}) {
+  return (Story: () => React.ReactElement) => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(['appConfig'], { feature_flags: featureFlags });
+    if (announcements) {
+      queryClient.setQueryData(['announcements'], announcements);
+    }
+
+    return (
+      <MemoryRouter initialEntries={[path]}>
+        <QueryClientProvider client={queryClient}>
+          <AuthContext.Provider value={mockAuthContextValue({ authenticated })}>
+            <GameContext.Provider value={mockGameContextValue}>
+              <Story />
+            </GameContext.Provider>
+          </AuthContext.Provider>
+        </QueryClientProvider>
+      </MemoryRouter>
+    );
+  };
+}
+
+const meta: Meta<typeof Navbar> = {
+  title: 'Layout/Navbar',
+  component: Navbar,
+  tags: ['autodocs'],
+  decorators: [withNavbarContext({})],
+};
+
+export default meta;
+type Story = StoryObj<typeof Navbar>;
+
+export const LoggedOut: Story = {
+  decorators: [withNavbarContext({ authenticated: false, path: '/' })],
+};
+
+export const LoggedIn: Story = {};
+
+/** `map` and `announcements` are `["testers"]`-gated by default - enabling them here via the seeded `appConfig` mirrors a tester/premium account. */
+export const WithAnnouncements: Story = {
+  decorators: [
+    withNavbarContext({
+      featureFlags: { announcements: 'all' },
+      announcements: {
+        unread_count: 1,
+        results: [
+          {
+            id: 1,
+            title: 'New feature: the map is live',
+            summary: 'Explore other characters at work on the world map.',
+            body: 'The map view is now available from the nav bar.',
+            published_at: '2026-08-01T00:00:00Z',
+            created_at: '2026-08-01T00:00:00Z',
+            is_read: false,
+          },
+          {
+            id: 2,
+            title: 'Scheduled maintenance',
+            summary: 'Brief downtime overnight on Aug 20.',
+            body: 'We are upgrading database infrastructure.',
+            published_at: '2026-07-20T00:00:00Z',
+            created_at: '2026-07-20T00:00:00Z',
+            is_read: true,
+          },
+        ],
+      },
+    }),
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button', { name: 'Announcements' }));
+
+    await waitFor(async () => {
+      await expect(canvas.getByText('New feature: the map is live')).toBeVisible();
+    });
+  },
+};
+
+export const WithMapEnabled: Story = {
+  decorators: [withNavbarContext({ featureFlags: { map: 'all' } })],
+};
diff --git a/frontend/src/testUtils/mockAuthContext.ts b/frontend/src/testUtils/mockAuthContext.ts
new file mode 100644
index 00000000..8479fd82
--- /dev/null
+++ b/frontend/src/testUtils/mockAuthContext.ts
@@ -0,0 +1,40 @@
+import type { AuthContextValue } from '../context/authContext';
+import type { User } from '../types';
+
+const mockUser: User = {
+  email: 'demo@example.com',
+  is_confirmed: true,
+  is_staff: false,
+  is_superuser: false,
+  date_of_birth: null,
+  timezone: 'UTC',
+};
+
+/**
+ * Minimal `AuthContextValue` for Storybook stories that read `useAuth()`
+ * directly (`Navbar`, `NavDrawer`, `Footer`). `authenticated: false` (the
+ * default) mirrors the real logged-out render - `AuthProvider` itself never
+ * calls the API when there are no stored tokens, so it doesn't need a mock.
+ * `authenticated: true` covers the logged-in nav state without a real
+ * session. Pass `overrides` for anything else (e.g. `user: { is_staff: true }`).
+ */
+export function mockAuthContextValue(
+  overrides: Partial<AuthContextValue> & { authenticated?: boolean } = {}
+): AuthContextValue {
+  const { authenticated = false, ...rest } = overrides;
+
+  return {
+    accessToken: authenticated ? 'mock-access-token' : null,
+    refreshToken: authenticated ? 'mock-refresh-token' : null,
+    isAuthenticated: authenticated,
+    user: authenticated ? mockUser : null,
+    setUser: () => {},
+    login: async () => null,
+    logout: () => {},
+    authFetch: async () => {
+      throw new Error('authFetch is not mocked in Storybook');
+    },
+    loading: false,
+    ...rest,
+  };
+}

From eb6a3e391538da4367bb61db0336c1285752850d Mon Sep 17 00:00:00 2001
From: Duncan Appleby <duncan@progressrpg.com>
Date: Fri, 14 Aug 2026 11:13:23 +0100
Subject: [PATCH 5/6] refactor: optimize imports and streamline activity timer
 functionality

---
 gameplay/tasks.py | 9 ++-------
 gameplay/utils.py | 5 ++++-
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/gameplay/tasks.py b/gameplay/tasks.py
index e1b02306..230b3b7b 100644
--- a/gameplay/tasks.py
+++ b/gameplay/tasks.py
@@ -6,7 +6,8 @@
 from django.utils import timezone
 
 from character.models import PlayerCharacterLink
-from .models import XpModifier
+from .models import ActivityTimer, XpModifier
+from .utils import broadcast_activity_timer
 
 DISCONNECT_TASK_CACHE_KEY = "disconnect_task:{player_id}"
 
@@ -26,9 +27,6 @@ def auto_complete_timer_on_disconnect(self, player_id: int):
     reconnecting within the grace window. Awards XP for elapsed time.
     Revoked by TimerConsumer.connect() if the player reconnects in time.
     """
-    from .models import ActivityTimer
-    from .utils import broadcast_activity_timer
-
     stored_task_id = cache.get(DISCONNECT_TASK_CACHE_KEY.format(player_id=player_id))
     if stored_task_id != self.request.id:
         return "superseded"
@@ -62,9 +60,6 @@ def auto_complete_timers_for_stale_players():
     heartbeat is older than STALE_TIMER_THRESHOLD (or was never set), and
     completes them the same way the disconnect grace period does.
     """
-    from .models import ActivityTimer
-    from .utils import broadcast_activity_timer
-
     cutoff = timezone.now() - STALE_TIMER_THRESHOLD
     stale_timers = (
         ActivityTimer.objects.select_related("player", "activity")
diff --git a/gameplay/utils.py b/gameplay/utils.py
index 2008f9b3..1128f239 100644
--- a/gameplay/utils.py
+++ b/gameplay/utils.py
@@ -32,7 +32,6 @@
 
 from character.models import Character
 from users.models import Player
-from gameplay.services.xp_modifiers import set_activity_active_modifiers
 
 import logging
 
@@ -48,6 +47,8 @@ def start_server_timers(act_timer: ActivityTimer):
 
     if act_timer.status in ["active", "paused", "waiting"]:
         try:
+            from gameplay.services.xp_modifiers import set_activity_active_modifiers
+
             act_timer.start()
             set_activity_active_modifiers(act_timer.player, is_active=True)
             result_text = "[START SERVER TIMERS] Timers successfully started"
@@ -72,6 +73,8 @@ def pause_server_timers(act_timer: ActivityTimer):
 
     try:
         if act_timer.status not in ["completed", "empty"]:
+            from gameplay.services.xp_modifiers import set_activity_active_modifiers
+
             act_timer.pause()
             set_activity_active_modifiers(act_timer.player, is_active=False)
             logger.debug("[PAUSE SERVER TIMERS] Activity timer successfully paused")

From 8cfd1c7640820853a7046ba2327256a172a0ddb1 Mon Sep 17 00:00:00 2001
From: Duncan Appleby <duncan@progressrpg.com>
Date: Fri, 14 Aug 2026 11:15:19 +0100
Subject: [PATCH 6/6] task: bump mkdocs and -material

---
 requirements-docs.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/requirements-docs.txt b/requirements-docs.txt
index 7ebe114c..592c1c96 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,2 +1,2 @@
-mkdocs>=1.6,<2.0
-mkdocs-material>=9.5,<10.0
+mkdocs>=1.6.1,<2.0
+mkdocs-material>=9.7.7,<10.0