CLAUDE.md — SP Lecture Studio
Mission
A production-grade, fully native Apple lecture recording and editing suite in one monorepo, for macOS, iPadOS and iOS. The user is a university instructor recording PDF-based lectures. Central workflow: import a PDF; present it; annotate live; capture microphone and optional camera; automatically pause/stop when configured; review a nondestructive edit; export a polished MP4 with synchronized annotations, optional subtitles, and an annotated PDF. Every device performs the complete workflow without any other device or server. Never claim a platform has been tested unless it was actually built and tested.
Nonnegotiable rules
- Native Swift and SwiftUI; PDFKit, PencilKit, AVFoundation, CoreMedia, VideoToolbox, Speech. No web view shell, Electron, React Native, Flutter or hosted editor.
- Shared domain, timing, project format, export pipeline and tests in Swift packages; platform adapters for capture, ink input, camera, permissions, UI.
- Offline-first: no sign-in, cloud, network, API key or MacLustr connection is needed to record, edit, render and export. AI features degrade gracefully.
- Never silently delete source recordings. Every edit is nondestructive, reversible and previewable.
- Reliability first: long sessions, crash recovery, low-disk alerts, interruptions, thermal/battery warnings, sleep prevention, continuous checkpoints.
- Privacy: permissions asked just in time; visible recording indicator; nothing uploaded by default.
- Never hardcode credentials, signing identities, provisioning data or secrets. Never print them.
- Be honest about SDK limits (background recording, external display, Pencil hover, camera multitasking). Render our own PDF canvas and ink stream; never use screen capture as the canonical source.
- No placeholder buttons, fake exports, simulated AI results or dummy recording paths in release functionality.
- Keep buildable checkpoints and record actual commands/results in PROGRESS.md.
Where things are
Package.swift— one SwiftPM package (LectureKit) whose targets live inPackages/<Name>/Sources; tests inTests/Unit,Tests/Integration.Apps/LectureStudio/project.yml— XcodeGen definition of the single Xcode project (macOS app, iOS/iPadOS app, UI tests). Runxcodegen generateafter adding files.docs/— ARCHITECTURE, PROJECT_FORMAT, RECORDING_PIPELINE, EXPORT_PIPELINE, SECURITY, QA, RELEASE.PROGRESS.md— checklist and evidence.scripts/—build-all.sh,test-all.sh [--long] [--ui] [--ui-mac],test-ui.sh,archive-macos.sh,notarize-macos.sh,archive-ios.sh,localize.py,make-icon.swift.
Working rules for this repository
- Build and test after every vertical slice:
scripts/build-all.sh && scripts/test-all.sh. Fix failures before adding scope. - Timeline time is
MediaTime(integer nanoseconds). Never useDoubleseconds for stored or accumulated time. - The event log (
events.jsonl) is append-only. Erase/undo are events (strokesRemoved/strokesRestored), never deletions. - Edits live in
edits.json(anEditHistory); source media, the PDF copy and the event log are never rewritten by editing or exporting. - Preview and export must go through the same code (
FrameCompositor,EditedAudioRenderer). Do not add a second rendering path. - UI strings are French in code (
Text("…"),String(localized:)); after adding strings run a build, thenscripts/localize.pyand add the English toscripts/translations-en.json. - Every first-party source file starts with the author header (project, file, description, author, contact).
Pitfalls found while building (keep these in mind)
- macOS 27:
List(selection:)does not select rows, andNavigationSplitView/HSplitViewmis-size their detail column → the app uses button rows and plainHStack+Divider. Pass models as parameters;@Environment(Model.self)crashes in sheets, toolbars and menus. - A system type named
LibraryItemexists: always writeLectureStorage.LibraryItemin the app. AVAudioFilefinalizes its header only onclose(); a checksum taken before that is wrong (SegmentedAudioWriter.closeCurrent).AVAssetWriterwrites side files next to its output; exports run in a private scratch folder that is removed afterwards.- PencilKit: the tool palette floats above sheets unless it is hidden (
session.paletteSuppressed); on iPhone it reports no obscured frame, so 72 pt is reserved; on iPad page navigation sits above the slide. PKStrokehas no identifier: strokes are matched by (creation date, random seed, point count, transform).- Recording state callbacks from
RecordingEnginearrive asynchronously on the main queue;ProjectSessionmirrorsengine.stateimmediately afterpause/resume/start. - Sandboxed Mac debug builds must always be signed by the team (never ad hoc): a signature change on the same bundle ID makes macOS hold the launch behind an app-data consent prompt. GUI launches and UI tests also hang while the Mac screen is locked.
set -o pipefail+grep -qon a pipe gives false failures in scripts (SIGPIPE): capture into a variable first.- Build outside
~/Desktop(~/Library/Developer/SPLectureStudio/DerivedData).