# CLAUDE.md — Focale

Appareil photo manuel + photothèque interrogeable. SwiftUI + AVFoundation + PhotoKit + Vision + Foundation Models. Ce fichier est la source de vérité du projet. Le lire avant toute modification.

# 1. Thèse produit

Deux produits qui se sauvent mutuellement.

Un appareil photo pro seul, c'est un marché saturé (Halide, Kino, Obscura, Moment). Une photothèque IA seule, c'est 40 000 photos à rattraper — des dizaines d'heures d'inférence avant la première valeur.

Ensemble, ils règlent le problème de l'autre : une photo prise dans Focale arrive déjà comprise. Le contexte est capturé au moment du déclenchement — intention, sujet, projet, réglages, lieu — gratuitement et sans ambiguïté. Pas de devinette, pas d'inférence coûteuse. La vieille bibliothèque se rattrape tranquillement en arrière-plan pendant que le produit est déjà utile.

La promesse : tout ce que tu photographies à partir d'aujourd'hui est parfaitement retrouvable.

Trois règles non négociables :

1. Rien ne quitte l'appareil. Jamais. La photothèque de quelqu'un est ce qu'il possède de plus intime. Aucune escalade cloud, même optionnelle, même sur les métadonnées. C'est l'argument de vente central — le renier une fois tue le produit.
2. Aucune photo n'est dupliquée, déplacée ou modifiée. Focale indexe la photothèque système par localIdentifier. L'utilisateur peut désinstaller demain sans rien perdre.
3. Utile avant que l'index soit complet. Les résultats arrivent progressivement, du plus récent au plus ancien.

# Positionnement de l'appareil photo

Contrôle et intention, jamais « meilleures photos ». Le mode Nuit n'est pas accessible aux apps tierces (voir §2) — en basse lumière, l'app Camera d'Apple gagnera toujours. Ne jamais promettre le contraire. Focale s'adresse à qui veut décider, pas à qui veut que ça marche tout seul.

# 2. Contraintes — lire avant de promettre quoi que ce soit

# Ce qui est accessible

# Ce qui n'est PAS accessible

• Mode Nuit. Jamais exposé aux apps tierces. Aucun contournement. Assumer ce déficit dans le positionnement.
• Mode Portrait complet d'Apple. La profondeur est disponible (AVCaptureDepthDataOutput), le rendu d'Apple ne l'est pas.
• Deep Fusion / Smart HDR s'appliquent dans le pipeline standard, mais sans contrôle fin. Le contourner est un choix de positionnement, comme Halide — pas un défaut à cacher.
• Remplacer Photos comme app par défaut. Impossible.

# Foundation Models

• A17 Pro minimum. Sur appareil non compatible, Focale reste un excellent appareil photo manuel avec une recherche Vision-only. Ce mode dégradé doit être bon, pas frustrant.
• Contexte 4096 / 8192 tokens. On ne passe jamais de longues listes de photos au modèle. Voir §5.
• Inférence sérialisée sur le Neural Engine. Les sessions parallèles s'exécutent en série. C'est LA contrainte du projet.
• Vision on-device (iOS 27) : image en entrée directe dans le prompt.

# PhotoKit — le risque produit le plus sous-estimé

Focale exige .authorized (Accès complet). En accès limité, le produit ne fonctionne pas du tout.

iOS relance périodiquement l'utilisateur pour l'inciter à réduire l'accès. Conséquences obligatoires :

• L'onboarding explique pourquoi avant d'afficher le dialogue système. Un dialogue nu = permission refusée = installation perdue.
• Détecter .limited et afficher un écran explicatif dédié, pas un message d'erreur.
• Le fait que rien ne sorte de l'appareil est l'argument qui débloque cette permission. Le dire à cet endroit précis.

# 3. Architecture

Focale/
├─ App/
├─ Capture/
│  ├─ Session/          AVCaptureSession, configuration, cycle de vie
│  ├─ Controls/         ISO, obturation, focus, WB — modèle + gestes
│  ├─ Output/           ProRAW, HEIC, écriture PhotoKit
│  ├─ Recipes/          presets utilisateur  ⚠️ voir §6
│  └─ Layout/           dispositions d'interface personnalisables  ⚠️ voir §6
├─ Intent/              contexte capturé au déclenchement  ⚠️ cœur du projet
├─ Index/
│  ├─ Vision/           étage 1 — OCR, visages, feature prints
│  ├─ Semantic/         étage 2 — Foundation Models, sur candidats seulement
│  ├─ Store/            SwiftData + vecteurs
│  └─ Scheduler/        BGProcessingTask, budget d'énergie
├─ Search/              requête naturelle → filtre → classement
├─ Library/             navigation, albums vivants, timeline
└─ Design/              tokens, typographie, thèmes

# 4. L'appareil photo

# Contexte de capture — la pièce qui différencie tout le projet

Au déclenchement, Focale enregistre bien plus que les EXIF, et sans coût d'inférence :

struct CaptureContext: Codable {
    let recipe: Recipe.ID?          // preset actif
    let project: Project.ID?        // projet déclaré par l'utilisateur
    let subjectHint: String?        // dicté ou tapé avant/après la prise
    let settings: ManualSettings    // ISO, vitesse, objectif, focus
    let scene: SceneSignal          // luminosité, mouvement, distance (LiDAR si dispo)
    let burstRole: BurstRole?       // sélection dans une rafale
    let place: PlaceRef?            // lieu, pas coordonnées brutes
}

Règles :

• Le contexte est écrit dans les métadonnées de l'actif en plus de la base locale. Si l'utilisateur désinstalle, l'information reste dans sa photo.
• Le mode Projet : l'utilisateur déclare « chantier cuisine », « voyage Gaspésie », « inventaire assurance ». Tout ce qui est pris ensuite est marqué. Un geste, une fois — puis zéro friction.
• Jamais de saisie obligatoire avant une photo. Le déclencheur doit toujours répondre instantanément. Le contexte s'ajoute autour, jamais devant.

# Règles de fer de la capture

• Le déclencheur est sacré. Aucune inférence, aucun disque, aucune allocation dans le chemin du déclenchement. Tout est différé.
• AVCaptureSession configurée hors du main thread, une seule fois. Reconfiguration en beginConfiguration/commitConfiguration.
• Toujours interroger les capacités avant d'exposer un contrôle : isAppleProRAWSupported, activeFormat.maxISO, plages d'exposition. Aucun contrôle affiché s'il n'est pas supporté par l'appareil — pas de bouton mort.
• Écriture PhotoKit via PHAssetCreationRequest, dans la photothèque système. Pas de bibliothèque parallèle, pas de sandbox privé.

# 5. L'indexeur — deux étages, obligatoirement

Le calcul à ne jamais oublier : 40 000 photos × 1 à 3 s d'inférence = 11 à 33 heures, en série. Une passe Foundation Models sur toute la bibliothèque est impossible. L'architecture entière découle de ça.

# Étage 1 — Vision framework, sur tout

Rapide, mature, faible coût énergétique. Couvre environ 80 % des besoins de recherche réels.

• VNRecognizeTextRequest — OCR. Le gagnant silencieux : reçus, factures, tableaux blancs, captures d'écran, panneaux, cartes d'affaires. C'est ce que les gens cherchent le plus et que Photos trouve le plus mal.
• VNGenerateImageFeaturePrintRequest — empreinte visuelle, gratuite. Donne la similarité (« des photos comme celle-ci ») et le regroupement de quasi-doublons sans aucun LLM.
• VNClassifyImageRequest — classification grossière.
• Détection de visages — regroupement local uniquement, jamais d'identification nommée sans action explicite de l'utilisateur.

# Étage 2 — Foundation Models, sur candidats seulement

Déclenché uniquement quand :

• la photo est prise dans Focale (contexte déjà présent → coût minime, valeur maximale) ;
• l'utilisateur ouvre une photo et demande explicitement ;
• une recherche ne trouve rien à l'étage 1 et il faut approfondir un sous-ensemble ;
• la photo est marquée importante (favori, partagée, souvent ouverte).

@Generable
struct PhotoSemantics {
    @Guide(description: "Ce que montre l'image, une phrase, factuelle")
    let gist: String

    @Guide(description: "Type de contenu")
    let kind: PhotoKind   // document, reçu, personne, lieu, objet, écran, nourriture, animal, autre

    @Guide(description: "Éléments cherchables présents dans l'image", .count(0...8))
    let entities: [String]

    @Guide(description: "Vrai si l'image contient une information à conserver (montant, date, code, adresse)")
    let hasActionableInfo: Bool
}

# Ordonnancement

• Du plus récent au plus ancien. Toujours. Les gens cherchent surtout dans les 2 dernières années.
• BGProcessingTask : en charge, Wi-Fi, écran éteint. Jamais sur batterie.
• Reprise incrémentale après interruption, sans jamais repartir de zéro.
• Honnêteté dans l'interface : « 12 400 / 41 000 photos indexées — les plus récentes sont déjà cherchables. Prêt dans environ 2 nuits. » Avec des résultats utilisables tout de suite. Un écran de chargement opaque de 20 heures est une désinstallation garantie.

# 6. Personnalisation — la promesse « ultra personnalisable »

C'est la raison d'être de l'appareil photo. Elle doit aller plus loin que des sliders.

# Recettes

Un preset complet, nommé, rappelable en un geste : réglages manuels, format (ProRAW/HEIC), objectif, look, comportement du déclencheur, contexte à appliquer. Exemples : « Documents » (correction de perspective, OCR prioritaire), « Nuit longue pose », « Chantier » (projet auto, grand-angle, horodatage visible).

• Recettes exportables et importables en fichier. Elles se partagent — c'est un canal d'acquisition gratuit.
• Une recette peut se déclencher automatiquement sur signal de scène (basse lumière, document détecté), avec une proposition, jamais un basculement silencieux.

# Disposition d'interface

L'utilisateur place ses propres contrôles : quels réglages sont visibles, où, à quelle taille, quels gestes les pilotent. Trois profils fournis (Simple / Photographe / Expert), tous modifiables.

• Mapping des gestes : glissement vertical gauche = ISO, horizontal = exposition, molette = focus… entièrement réassignable.
• Bouton Camera Control et bouton Action assignables à une recette précise.
• Retour haptique paramétrable par contrôle (crans à chaque tiers d'IL, par exemple).

# Looks

Rendus appliqués en non-destructif, jamais cuits dans l'original. Courbes, teinte, grain, virage. Toujours réversible, toujours avec l'original intact.

# Règle qui encadre tout ça

Les valeurs par défaut doivent être excellentes. La personnalisation est une profondeur pour ceux qui la cherchent, pas un devoir à l'installation. Le premier lancement doit donner une bonne photo en trois secondes, sans réglage. Une app qui exige d'être configurée avant d'être bonne perd la majorité de ses utilisateurs le premier jour.

# 7. Recherche

• Entrée en langage naturel. Le modèle analyse la requête (petit prompt, coût dérisoire), il ne parcourt pas les photos.
• La requête est convertie en filtre structuré : période, lieu, type, entités, texte OCR, similarité visuelle. Le filtre s'exécute sur la base locale — instantané, sur 40 000 photos comme sur 400.
• Le classement combine : correspondance OCR, distance de feature print, contexte de capture, récence.
• Foundation Models n'intervient qu'au bout, pour départager un petit ensemble de candidats si nécessaire.
• Requêtes cibles à faire fonctionner parfaitement (à tester en continu) : « le reçu du garage l'automne passé », « la photo du tableau blanc de la réunion budget », « où j'ai stationné la semaine passée », « les photos comme celle-ci », « le numéro de série de la laveuse ».

# Albums vivants

Un album défini par une requête, pas par une sélection. « Tous mes reçus 2026 », « chantier cuisine », « documents avec une date d'expiration ». Il se remplit tout seul à mesure que tu photographies.

# 8. Honnêteté du modèle

• Une description générée est visuellement distincte d'une donnée réelle (EXIF, OCR, lieu). Toujours.
• L'OCR prime sur le modèle pour tout ce qui est chiffre, date, montant, code. Le modèle 3B peut halluciner un montant ; l'OCR non. Ne jamais afficher un chiffre venu du LLM comme un fait.
• Sur incertitude, ne rien dire. Une photo mal comprise vaut mieux qu'une photo faussement étiquetée — l'utilisateur perdrait confiance dans tout l'index.
• Aucune identification de personne sans action explicite. Aucun regroupement de visages nommé automatiquement.
• Les garde-fous du modèle peuvent refuser des images légitimes. Traiter le refus comme un état normal : la photo reste indexée par l'étage 1, sans message d'erreur.

# 9. Performance & énergie

• Le déclencheur répond en moins de 50 ms, toujours. C'est la métrique numéro un du produit. Mesurée à chaque build.
• Aperçu à 60 fps sans chute pendant l'indexation. Si l'indexeur tourne, il est suspendu dès l'ouverture de la caméra.
• File d'inférence à priorité : geste utilisateur > photo qu'on regarde > arrière-plan. Annulation immédiate au changement d'écran.
• Budget thermique : surveiller ProcessInfo.thermalState, suspendre l'étage 2 dès .fair.
• Taille de l'index : viser moins de 500 Mo pour 50 000 photos. Vignettes via PhotoKit, jamais stockées en double.

# 10. Conventions de code

• SwiftUI, iOS 27+, @Observable. Swift 6, concurrence stricte.
• AVCaptureSession sur sa propre file série, jamais sur le main actor. L'UI de capture est @MainActor.
• Jamais de String libre en sortie de modèle. Toujours @Generable.
• Toute capacité matérielle est vérifiée avant d'être exposée. Aucune supposition sur le modèle d'iPhone.
• Chaque fonctionnalité IA a un chemin de repli Vision-only testé. La suite de tests tourne avec Foundation Models désactivé.
• Nommage utilisateur en français ; code, commentaires et commits en anglais.

# 11. Ordre de construction

1. Appareil photo manuel excellent. Contrôles, ProRAW, recettes, écriture PhotoKit. Zéro IA. Vendable seul dès cette étape — et c'est le test : si personne ne le veut ici, l'IA ne le sauvera pas.
2. Contexte de capture + projets. Invisible, mais c'est la fondation de la recherche.
3. Étage 1 Vision sur les nouvelles photos, puis rétroactif. L'OCR d'abord : c'est le gain le plus spectaculaire pour l'effort le plus faible.
4. Recherche naturelle + albums vivants. Le moment « je ne peux plus revenir à Photos ».
5. Étage 2 Foundation Models sur candidats.
6. Personnalisation avancée : dispositions, mapping de gestes, looks, partage de recettes.

# 12. Risques connus