SPB Git

Repository Public

CLAUDE.md 5.9 KB 66 lines markdown

1<!--2SP Lecture Studio3File: CLAUDE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# CLAUDE.md — SP Lecture Studio89## Mission10A production-grade, fully native Apple lecture recording and editing suite in one monorepo, for macOS, iPadOS and iOS. The user is a11university instructor recording PDF-based lectures. Central workflow: import a PDF; present it; annotate live; capture microphone and12optional camera; automatically pause/stop when configured; review a nondestructive edit; export a polished MP4 with synchronized13annotations, optional subtitles, and an annotated PDF. Every device performs the complete workflow without any other device or server.14Never claim a platform has been tested unless it was actually built and tested.1516## Nonnegotiable rules171. Native Swift and SwiftUI; PDFKit, PencilKit, AVFoundation, CoreMedia, VideoToolbox, Speech. No web view shell, Electron, React Native, Flutter or hosted editor.182. Shared domain, timing, project format, export pipeline and tests in Swift packages; platform adapters for capture, ink input, camera, permissions, UI.193. Offline-first: no sign-in, cloud, network, API key or MacLustr connection is needed to record, edit, render and export. AI features degrade gracefully.204. Never silently delete source recordings. Every edit is nondestructive, reversible and previewable.215. Reliability first: long sessions, crash recovery, low-disk alerts, interruptions, thermal/battery warnings, sleep prevention, continuous checkpoints.226. Privacy: permissions asked just in time; visible recording indicator; nothing uploaded by default.237. Never hardcode credentials, signing identities, provisioning data or secrets. Never print them.248. 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.259. No placeholder buttons, fake exports, simulated AI results or dummy recording paths in release functionality.2610. Keep buildable checkpoints and record actual commands/results in PROGRESS.md.2728## Where things are29- `Package.swift` — one SwiftPM package (`LectureKit`) whose targets live in `Packages/<Name>/Sources`; tests in `Tests/Unit`, `Tests/Integration`.30- `Apps/LectureStudio/project.yml` — XcodeGen definition of the single Xcode project (macOS app, iOS/iPadOS app, UI tests). Run `xcodegen generate` after adding files.31- `docs/` — ARCHITECTURE, PROJECT_FORMAT, RECORDING_PIPELINE, EXPORT_PIPELINE, SECURITY, QA, RELEASE. `PROGRESS.md` — checklist and evidence.32- `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`.3334## Working rules for this repository35- Build and test after every vertical slice: `scripts/build-all.sh && scripts/test-all.sh`. Fix failures before adding scope.36- Timeline time is `MediaTime` (integer nanoseconds). Never use `Double` seconds for stored or accumulated time.37- The event log (`events.jsonl`) is append-only. Erase/undo are events (`strokesRemoved` / `strokesRestored`), never deletions.38- Edits live in `edits.json` (an `EditHistory`); source media, the PDF copy and the event log are never rewritten by editing or exporting.39- Preview and export must go through the same code (`FrameCompositor`, `EditedAudioRenderer`). Do not add a second rendering path.40- 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`.41- Every first-party source file starts with the author header (project, file, description, author, contact).4243## Pitfalls found while building (keep these in mind)44- 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.45- A system type named `LibraryItem` exists: always write `LectureStorage.LibraryItem` in the app.46- `AVAudioFile` finalizes its header only on `close()`; a checksum taken before that is wrong (`SegmentedAudioWriter.closeCurrent`).47- `AVAssetWriter` writes side files next to its output; exports run in a private scratch folder that is removed afterwards.48- 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.49- `PKStroke` has no identifier: strokes are matched by (creation date, random seed, point count, transform).50- Recording state callbacks from `RecordingEngine` arrive asynchronously on the main queue; `ProjectSession` mirrors `engine.state` immediately after `pause` / `resume` / `start`.51- 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.52- `set -o pipefail` + `grep -q` on a pipe gives false failures in scripts (SIGPIPE): capture into a variable first.53- Build outside `~/Desktop` (`~/Library/Developer/SPLectureStudio/DerivedData`).5455<!-- spb-source-governance:start -->56## Source header policy (SP Boucher)5758When creating or modifying eligible first-party source files, follow the SP Boucher Source Header59Policy. Preserve existing copyright and license notices, select the correct language-specific60template, and avoid adding identifying information to anonymous academic submission artifacts.6162- Repository policy: `.spb-source-governance.toml` (project, contact, verified rights, license).63- Add or refresh headers with `spb-header apply --repo .`; verify with `spb-header check --repo .`.64- Never hand-write a header, never add one to generated, vendored, third-party or data files.65<!-- spb-source-governance:end -->66
Files main
Menu

Theme