SPB Git

Repository Public

CLAUDE.md 5.3 KB

# 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

  1. Native Swift and SwiftUI; PDFKit, PencilKit, AVFoundation, CoreMedia, VideoToolbox, Speech. No web view shell, Electron, React Native, Flutter or hosted editor.
  2. Shared domain, timing, project format, export pipeline and tests in Swift packages; platform adapters for capture, ink input, camera, permissions, UI.
  3. Offline-first: no sign-in, cloud, network, API key or MacLustr connection is needed to record, edit, render and export. AI features degrade gracefully.
  4. Never silently delete source recordings. Every edit is nondestructive, reversible and previewable.
  5. Reliability first: long sessions, crash recovery, low-disk alerts, interruptions, thermal/battery warnings, sleep prevention, continuous checkpoints.
  6. Privacy: permissions asked just in time; visible recording indicator; nothing uploaded by default.
  7. Never hardcode credentials, signing identities, provisioning data or secrets. Never print them.
  8. 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.
  9. No placeholder buttons, fake exports, simulated AI results or dummy recording paths in release functionality.
  10. Keep buildable checkpoints and record actual commands/results in PROGRESS.md.

# Where things are

  • Package.swift — one SwiftPM package (LectureKit) whose targets live in Packages/<Name>/Sources; tests in Tests/Unit, Tests/Integration.
  • Apps/LectureStudio/project.yml — XcodeGen definition of the single Xcode project (macOS app, iOS/iPadOS app, UI tests). Run xcodegen generate after 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 use Double seconds 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 (an EditHistory); 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, then scripts/localize.py and add the English to scripts/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, and NavigationSplitView / HSplitView mis-size their detail column → the app uses button rows and plain HStack + Divider. Pass models as parameters; @Environment(Model.self) crashes in sheets, toolbars and menus.
  • A system type named LibraryItem exists: always write LectureStorage.LibraryItem in the app.
  • AVAudioFile finalizes its header only on close(); a checksum taken before that is wrong (SegmentedAudioWriter.closeCurrent).
  • AVAssetWriter writes 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.
  • PKStroke has no identifier: strokes are matched by (creation date, random seed, point count, transform).
  • Recording state callbacks from RecordingEngine arrive asynchronously on the main queue; ProjectSession mirrors engine.state immediately after pause / 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 -q on a pipe gives false failures in scripts (SIGPIPE): capture into a variable first.
  • Build outside ~/Desktop (~/Library/Developer/SPLectureStudio/DerivedData).
Files main
Menu

Theme