@sincpro/mobile 0.1.1 → 0.3.1

package/README.md

@@ -1,91 +1,875 @@
 # @sincpro/mobile
 
-Core del **framework móvil Sincpro** (React Native / Expo): infraestructura offline-first (DB, cola/eventos, cron), patrones DDD, adapters base, composición **module-driven** y el `AppShell`. Consume el design system `@sincpro/mobile-ui`.
+**Enterprise mobile application framework for React Native / Expo** — built on hexagonal architecture, domain-driven design, and offline-first infrastructure.
 
-> 🤖 **¿Sos un agente de IA?** Leé primero [`AGENTS.md`](AGENTS.md) — orientación rápida del ecosistema, patrones y trampas. Si algo se comporta raro, [`docs/GOTCHAS.md`](docs/GOTCHAS.md).
+Enterprise mobile development has always been hard. Applications need to work without internet, recover from failures gracefully, sync data when connectivity returns, manage authentication state, handle background tasks, print documents, and do all of this across iOS and Android with a single codebase. Each project that solves these problems from scratch solves them differently — and then someone has to maintain those differences forever.
 
-## Filosofía
+`@sincpro/mobile` is Sincpro's answer to that problem. This framework encodes proven enterprise patterns once — event queues, dead-letter queues, domain event sourcing, offline-first storage, cron workers, adapter ports — and every app built on it inherits those capabilities by default.
 
-El objetivo es **generar apps móviles de negocio muy rápido** componiendo piezas estables, no escribir cada app desde cero. Principios:
+**Sincpro maintains this.** The source is open and anyone can read it. What Sincpro provides is the commitment behind it: stable contracts, long-term API support, updates as platforms evolve, and people accountable for the behaviors your business depends on. This is not a project that gets abandoned. It is infrastructure for the new era of enterprise mobile development, and Sincpro intends to maintain it for the teams and clients that build on top of it.
 
-- **Framework, no monolito.** Un ecosistema de paquetes publicables; cada app es delgada y declara solo sus dominios.
-- **Module-driven + inversión de dependencia.** El core no conoce los negocios. Cada dominio es un `DomainModule` que la app registra; el `orchestrator` alimenta cola, repos, migraciones, cron y temas desde los módulos registrados. Agregar/mover un dominio no toca el core.
-- **Offline-first.** SQLite + cola de eventos persistente (con DLQ y reintentos) + sincronización; la app funciona sin red y reconcilia al volver.
-- **Hexagonal.** El dominio define puertos (`IPrinterDriver`, `IRepository`, `IRemoteClient`); los adapters concretos viven afuera y se inyectan. El core es agnóstico de hardware y de backend.
-- **Frontera real verificable.** Capas con dirección estricta `apps → mobile-odoo → mobile → mobile-ui`; el design system no sabe de negocio; los enums/eventos tienen un punto único de export.
+> **AI agent?** Read [`AGENTS.md`](AGENTS.md) first — ecosystem orientation, patterns, and traps. Known runtime issues live in [`docs/GOTCHAS.md`](docs/GOTCHAS.md).
 
-## Ecosistema
+---
 
-| Paquete                | Rol                                                                                         |
-| ---------------------- | ------------------------------------------------------------------------------------------- |
-| `@sincpro/mobile`      | Core: infra, patrones DDD, `framework/` (DomainModule, createApp, orchestrator), `AppShell` |
-| `@sincpro/mobile-ui`   | Design system standalone (sin router, sin dominios)                                         |
-| `@sincpro/mobile-odoo` | Integración Odoo **opcional** (OdooClient, auth, server, partner)                           |
-| `sincpro-mobile-<app>` | Apps de negocio (tickets, distribution) que componen lo anterior                            |
+## ⚡ Quick Start
 
-## Instalación
+Here is the minimum to get a working enterprise app running:
 
 ```bash
 npx expo install @sincpro/mobile @sincpro/mobile-ui
 ```
 
-`@sincpro/mobile-ui` es peer dependency (lo provee la app). Para integrar Odoo: `@sincpro/mobile-odoo` (opcional).
+```tsx
+// 1. Define your domain module
+import { DomainModule } from "@sincpro/mobile/framework/domain_module";
+import type { Subscriber } from "@sincpro/mobile/domain/event_sourcing";
+import type { CronWorker } from "@sincpro/mobile/infrastructure/workers";
 
-## Instanciar una app
+class SalesModule extends DomainModule {
+  readonly key = "SALES";
+  readonly name = "Sales";
 
-Una app define sus dominios como **clases que extienden `DomainModule`** y las compone con `createAppShell`:
+  override subscribers(): Subscriber[] {
+    return SalesSubscribers;
+  }
+  override crons(): CronWorker[] {
+    return SalesCronJobs;
+  }
+}
 
-```tsx
+const salesModule = new SalesModule();
+
+// 2. Wire the app shell — one call does everything
 import { createAppShell, createTheme } from "@sincpro/mobile";
+
+export default createAppShell({
+  theme: createTheme({ accent: "#0EA5E9" }),
+  domains: [salesModule],
+  ui: { [salesModule.key]: SalesScreen },
+  activeDomain: salesModule.key,
+});
+```
+
+`createAppShell` runs database migrations, starts the event queue, registers cron workers, applies the theme, loads fonts, and mounts the app — all from a single configuration object.
+
+---
+
+## 📑 Table of Contents
+
+1. [Why This Framework Exists](#why-this-framework-exists)
+2. [Architecture Overview](#architecture-overview)
+3. [Ecosystem](#ecosystem)
+4. [Key Features](#key-features)
+5. [Creating a DomainModule](#creating-a-domainmodule)
+6. [AppShell Configuration](#appshell-configuration)
+7. [Theme Configuration](#theme-configuration)
+8. [Brand Font Configuration](#brand-font-configuration)
+9. [Public API](#public-api)
+10. [Subpaths](#subpaths)
+11. [Development](#development)
+
+---
+
+## 🔍 Why This Framework Exists
+
+### The Enterprise Mobile Problem
+
+Building a business mobile application is not the same as building a consumer app. Business apps need to work in warehouses with no Wi-Fi. They need to print receipts to Bluetooth thermal printers. They need to sync order data when the connection comes back, in the right order, without duplicates. They need to run background jobs that don't drain the battery. They need authentication that safely clears sensitive data on logout. They need dark and light themes that match the brand manual. They need to ship fast and be maintained for years.
+
+None of this is hard in isolation. All of it together, across iOS and Android, from scratch, for every project — is expensive, inconsistent, and difficult to maintain.
+
+### The AI Era Problem
+
+AI tools can generate code faster than ever. That makes the absence of a framework _more_ dangerous, not less. When there is no shared architecture, AI-generated code is consistent only with itself — each prompt produces a different pattern, a different naming convention, a different approach to the same problem. The velocity is real. The maintenance cost is also real.
+
+With `@sincpro/mobile`, AI tools have clear patterns to follow: `DomainModule`, `createAppShell`, `Subscriber`, `CronWorker`, `Entity.addDomainEvent`. Code generated within the framework is framework-compliant by default. Human reviewers can audit it quickly. The codebase stays navigable.
+
+### The Multi-Platform Bet
+
+React Native and Expo are the right foundation for enterprise cross-platform mobile in 2025 and beyond. A single TypeScript codebase, native performance, the full JavaScript ecosystem, and Expo's managed platform for OTA updates and native modules. Sincpro commits to maintaining the enterprise layer on top of this foundation as it evolves — consumers get platform upgrades without rewriting their business logic.
+
+### What Sincpro Provides
+
+Open-source software is valuable. Maintained open-source software is rare. The difference is people: engineers who triage issues, update dependencies, handle platform breaking changes, document traps they found in production, and preserve behavioral contracts across major versions.
+
+Sincpro builds and maintains `@sincpro/mobile` because we build and support the clients that run on it. When a behavior breaks, we fix it. When Expo upgrades their SDK, we absorb the migration. When a new enterprise pattern proves itself in production, we promote it into the framework so every app inherits it. That is the commitment.
+
+---
+
+## 🏗️ Architecture Overview
+
+The framework is organized in strict layers with enforced one-way dependency flow:
+
+```
+┌─────────────────────────────────────────────────────┐
+│              Business Apps                          │
+│    sincpro-mobile-tickets / distribution / …        │
+└────────────────────────┬────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────┐
+│           @sincpro/mobile-odoo  (optional)          │
+│         OdooClient · Auth · Partner sync            │
+└────────────────────────┬────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────┐
+│              @sincpro/mobile  ◄── YOU ARE HERE       │
+│                                                     │
+│  framework/      DomainModule · Kernel · Orchestrator│
+│  domain/         Entity · Event Sourcing · Ports    │
+│  infrastructure/ EventBus · CronWorker · DLQ        │
+│  adapters/       Network · Bluetooth · Geo · WebView│
+│  services/       Printer · DLQ · Events · Network  │
+│  entrypoints/    AppShell · DB · Queue · Cron       │
+└────────────────────────┬────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────┐
+│              @sincpro/mobile-ui                     │
+│         Design System — no domain knowledge         │
+└─────────────────────────────────────────────────────┘
+```
+
+### Key Architectural Principles
+
+- **Hexagonal Architecture (Ports and Adapters).** The domain layer defines interfaces (`IPrinterDriver`, `IRepository`). Concrete implementations live outside and are injected. The core never imports hardware SDKs.
+- **Domain-Driven Design.** Each bounded context is a `DomainModule`. The framework orchestrates them; they never know about each other.
+- **Offline-First.** Every domain event is persisted to SQLite before it is processed. Events survive app restarts and process them on recovery.
+- **Strict layer boundaries.** A lower layer cannot import from a higher one. `mobile-ui` has no imports from `@sincpro/mobile`.
+
+---
+
+## 🗂️ Ecosystem
+
+| Package                | Role                                                                 |
+| ---------------------- | -------------------------------------------------------------------- |
+| `@sincpro/mobile`      | Core framework: infrastructure, DDD patterns, `AppShell`             |
+| `@sincpro/mobile-ui`   | Standalone design system (no domain logic)                           |
+| `@sincpro/mobile-odoo` | **Optional** Odoo 17 integration (OdooClient, auth, partner, server) |
+| `sincpro-mobile-<app>` | Business apps (tickets, distribution) that compose the above         |
+
+Dependency direction is enforced: apps use everything; `mobile-ui` knows nothing upstream.
+
+---
+
+## 🔑 Key Features
+
+### ✅ Module-Driven Architecture
+
+Each bounded context is a class that extends `DomainModule`. It declares its own repositories, migrations, subscribers, and cron workers. The `Kernel` aggregates them all; the `Orchestrator` manages their lifecycle. The core never changes when a domain is added or removed.
+
+```tsx
+class InvoiceModule extends DomainModule {
+  readonly key = "INVOICE";
+  readonly name = "Invoice";
+
+  override repositories() {
+    return {
+      invoiceRepo: new InvoiceRepository(),
+      invoiceLineRepo: new InvoiceLineRepository(),
+    };
+  }
+
+  override migrations(): IMigration[] {
+    return [CreateInvoicesTable, CreateInvoiceLinesTable];
+  }
+
+  override subscribers(): Subscriber[] {
+    return [InvoiceCreatedSubscriber, InvoiceVoidedSubscriber, SyncInvoiceSubscriber];
+  }
+
+  override crons(): CronWorker[] {
+    return [SyncPendingInvoicesCron];
+  }
+
+  // Tables to preserve when the domain is wiped (e.g. on logout)
+  override persistOnReset(): string[] {
+    return ["invoice_templates"];
+  }
+}
+```
+
+### ✅ Offline-First Event Queue
+
+Every domain event is persisted to SQLite before any subscriber processes it. If the app is killed mid-processing, the event is replayed on restart. Events requiring network connectivity are held until connectivity returns.
+
+**Poll cycle:** EventBus polls every **800ms**, with exponential backoff (×1.5 multiplier, max **30s**) when the queue is empty or the device is offline. The interval resets immediately when a new event is published or connectivity is restored.
+
+```tsx
+import { Entity } from "@sincpro/mobile/domain/entity";
+
+class Order extends Entity {
+  status = "pending";
+
+  confirm() {
+    this.status = "confirmed";
+    // Persisted to SQLite before processig — survives app restart
+    this.addDomainEvent(OrderConfirmedEvent, { orderId: this.uuid });
+  }
+}
+
+// Subscriber processes the event asynchronously
+class OrderConfirmedSubscriber extends Subscriber {
+  listen = [OrderConfirmedEvent];
+  requiresAuth = true;
+
+  async process(event: OrderConfirmedEvent): Promise<void> {
+    await syncOrderToServer(event.orderId);
+  }
+}
+```
+
+### ✅ Dead Letter Queue (DLQ)
+
+Events that exceed the maximum retry attempts (`MAX_ATTEMPTS = 1` per cycle) are automatically moved to the dead letter queue with the full error message and failure timestamp. Operations teams can inspect, retry in bulk, or permanently delete failed events.
+
+```tsx
+import { deadLetterQueueUseCases } from "@sincpro/mobile/services/dlq.service";
+
+// Inspect failed events
+const failed = await deadLetterQueueUseCases.getFailedEvents();
+
+// Retry a single event (fresh uuid, reset attempts)
+await deadLetterQueueUseCases.retryFailedEvent(failed[0]);
+
+// Bulk retry — returns { success: number, failed: number }
+const result = await deadLetterQueueUseCases.retryMultipleFailedEvents(failed);
+
+// Remove permanently
+await deadLetterQueueUseCases.deleteFailedEvent(failed[0]);
+```
+
+### ✅ Domain Entity with Event Sourcing
+
+`Entity` is the aggregate root. It collects domain events during a business operation and publishes them atomically. Events carry tracing fields (`correlationId`, `aggregateId`, `sequence`) for transaction support and SAGA patterns.
+
+```tsx
+import { Entity } from "@sincpro/mobile/domain/entity";
+
+class Invoice extends Entity {
+  remoteId?: string;
+  status: "draft" | "sent" | "paid" = "draft";
+  lines: InvoiceLine[] = [];
+
+  addLine(line: InvoiceLine) {
+    this.lines.push(line);
+    // correlationId groups all events from this operation
+    this.addDomainEvent(InvoiceLineAddedEvent, { invoiceId: this.uuid, lineId: line.uuid });
+  }
+
+  send() {
+    this.status = "sent";
+    // All events from this call share the same correlationId and sequence
+    this.addDomainEvent(InvoiceSentEvent, { invoiceId: this.uuid, sentAt: new Date() });
+    await this.publishAllDomainEvents();
+  }
+}
+```
+
+**Entity lifecycle methods:**
+
+| Method                            | Description                                                                   |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `addDomainEvent(Event, payload?)` | Enqueues an event with auto-assigned aggregateId, correlationId, and sequence |
+| `addDomainEventWithEntity(Event)` | Enqueues event with the entire entity as the `record` field                   |
+| `publishAllDomainEvents()`        | Async: persists all pending events, clears the internal queue                 |
+| `publishAllDomainEventsSync()`    | Sync: publishes immediately, throws on any failure                            |
+| `copyDomainEventsFrom(source)`    | Transfers events from another entity (re-aggregating)                         |
+
+### ✅ Remote Entity Sync
+
+`RemoteEntity` extends `Entity` with sync state tracking for entities that mirror data from a remote server. It manages the full lifecycle from pending local creation to confirmed remote sync.
+
+```tsx
+import { RemoteEntity } from "@sincpro/mobile/domain/entity";
+
+class Product extends RemoteEntity {
+  name: string = "";
+  price: number = 0;
+  // remoteState: "SYNCED" | "PENDING" | "FAILED"
+  // remoteId?: string — the server's ID once synced
+
+  static fromApiResponse(data: ApiProduct): Product {
+    return Product.fromRemoteDTO(data);
+  }
+
+  syncWithServer(updated: ApiProduct) {
+    this.mergeWithRemote(updated); // preserves uuid + eventIds
+    this.markAsSynced();
+  }
+
+  toApiPayload() {
+    return this.remotePayload(); // serializes to API format
+  }
+}
+```
+
+### ✅ Background Cron Workers
+
+`CronWorker` schedules recurring background tasks. Workers under 15 minutes use `setInterval` (foreground); workers at or above 15 minutes register with `expo-background-task` for true background execution.
+
+```tsx
+import { CronWorker } from "@sincpro/mobile/infrastructure/workers";
+
+const SyncInvoicesCron = new CronWorker(
+  "sync-invoices", // task name (must be globally unique)
+  async () => {
+    const pending = await invoiceRepo.findPendingSync();
+    for (const invoice of pending) {
+      await apiClient.syncInvoice(invoice);
+    }
+  },
+  15, // interval in minutes (>= 15 → background capable)
+  true, // requiresAuth — won't run if the session is unauthenticated
+);
+```
+
+The `Orchestrator` starts, stops, and re-syncs workers automatically when domains are activated/deactivated or when the authentication state changes.
+
+### ✅ Authentication Lifecycle
+
+The `Orchestrator` manages a global authentication state that gates subscribers and cron workers. Marking the session unauthenticated can optionally wipe the event queue and reset the database — leaving only the tables declared in `persistOnReset()`.
+
+```tsx
+import { orchestrator } from "@sincpro/mobile";
+
+// User signs in
+await orchestrator.authenticateSession();
+// → Re-syncs queue subscribers and cron workers for active domains
+
+// User signs out — clears queue + resets DB (except persisted tables)
+await orchestrator.unauthenticateSession(true);
+
+// Resume after app goes to background and returns
+await orchestrator.restoreSession();
+// → Drains the event queue and re-syncs crons
+
+// Domain enable / disable at runtime
+await orchestrator.enableDomain("ODOO");
+await orchestrator.disableDomain("ODOO");
+```
+
+All state transitions are protected by a mutex — concurrent calls are serialized.
+
+### ✅ Connectivity Awareness
+
+The framework knows whether the device has internet access and routes work accordingly. Events marked `requiresNetwork = true` are held in the queue until connectivity is confirmed. Subscribers can respond directly to connectivity changes via domain events.
+
+```tsx
+class SyncOrderEvent extends DomainEvent {
+  static requiresNetwork = true; // Won't process while offline
+}
+
+// Check status at any point
+import { networkUseCases } from "@sincpro/mobile/services/network.service";
+
+const status = await networkUseCases.getNetworkStatus();
+// { isConnected: boolean, isInternetReachable: boolean | null, type: "wifi"|"cellular"|…, ipAddress }
+```
+
+The EventBus subscribes to `InternetIsDownEvent` / `InternetIsUpEvent` internally — when connectivity is lost it increases the poll interval, and when it is restored it resets to 800ms and drains any held events immediately.
+
+### ✅ Bluetooth Printer Integration
+
+The printer port (`IPrinterDriver`) is defined by the framework; the concrete driver is registered by the app. The `PrinterService` wraps it with connection management, permission handling, and a grace-reconnect strategy.
+
+```tsx
+// Register the adapter before AppShell boots
+import { printerService } from "@sincpro/mobile/services/printer.service";
+import { PrinterAdapter } from "./adapters/Printer.adapter"; // your Bluetooth impl
+
+printerService.setDriver(PrinterAdapter);
+
+// Then use the service anywhere
+await printerService.connect(deviceAddress, "Printer Name");
+await printerService.printText("=== RECEIPT ===\nItem: Widget\nTotal: $12.00");
+await printerService.printImageBase64(base64Png);
+await printerService.printHtml(htmlString); // converts to PDF (576px thermal width)
+
+// Capture a React Native view and print it
+await printerService.printFromView(receiptViewRef);
+```
+
+**Grace reconnect:** If printing fails, the service automatically disconnects, reconnects to the last saved printer, and retries once — without surfacing the error to the user.
+
+### ✅ WebView Print Interception
+
+The framework ships injectable scripts that intercept `window.print()` calls inside a WebView, capture the document as a PNG via `html2canvas`, and forward it to React Native for Bluetooth printing.
+
+```tsx
+import { WebViewAdapter } from "@sincpro/mobile/adapters/webview";
+
+<WebView
+  injectedJavaScriptBeforeContentLoaded={WebViewAdapter.getDefaultInterceptors()
+    .map((s) => s.script)
+    .join("\n")}
+  onMessage={({ nativeEvent }) => {
+    // Framework base_module handles PRINT_IMAGE automatically
+    // via ProcessWebViewMessageSubscriber → PrintImageSubscriber
+    EventBus.publishSync(new WebViewMessageReceivedEvent({ raw: nativeEvent.data }));
+  }}
+/>;
+```
+
+Available interceptors: `printInterceptor` (default), `ajaxInterceptor` (debug), `contentHeightReporter`.
+
+### ✅ Activity Monitoring
+
+`useCommon()` exposes real-time visibility into queue and cron activity — what is running, what failed, and how long it has been running. Use this to build status indicators, loading states, and error recovery UI.
+
+```tsx
+import { useCommon } from "@sincpro/mobile";
+
+function StatusBar() {
+  const { currentActivity, lastError, isProcessing, dismiss } = useCommon();
+
+  if (lastError)
+    return (
+      <Banner variant="error" onDismiss={dismiss}>
+        {lastError.label} failed: {lastError.error}
+      </Banner>
+    );
+
+  if (isProcessing) return <ActivityIndicator label={currentActivity?.label ?? "Working…"} />;
+
+  return null;
+}
+```
+
+**`ICommonContext` full shape:**
+
+| Field                    | Type                            | Description                              |
+| ------------------------ | ------------------------------- | ---------------------------------------- |
+| `currentActivity`        | `Activity \| undefined`         | Currently running queue or cron task     |
+| `lastError`              | `Activity \| undefined`         | Last failed task (auto-clears after 10s) |
+| `isProcessing`           | `boolean`                       | True while any task is active or errored |
+| `dismiss()`              | `() => void`                    | Clears `lastError`                       |
+| `debugMode`              | `boolean`                       | Developer debug toggle (persisted)       |
+| `colorScheme`            | `"light" \| "dark" \| "system"` | Current color scheme (persisted)         |
+| `setColorScheme(scheme)` | function                        | Switches theme + persists preference     |
+| `timezone`               | `string \| null`                | Persisted timezone setting               |
+| `updateTimezone(tz)`     | function                        | Updates and persists                     |
+| `hasGeoPermission`       | `boolean`                       | Current geo permission state             |
+| `requestGeoPermission()` | `async () => boolean`           | Requests location permission             |
+| `checkGeoPermission()`   | `async () => void`              | Rechecks without prompting               |
+
+### ✅ Domain Switcher
+
+Apps that compose multiple domains can switch the active UI at runtime without any navigation library setup. The domain that is not displayed is still running — its queue subscribers and cron workers remain active.
+
+```tsx
+import { useDomainSwitcher } from "@sincpro/mobile";
+
+function AppSwitcher() {
+  const { activeDomain, switchTo } = useDomainSwitcher();
+
+  return (
+    <Navigation.SegmentedControl
+      value={activeDomain}
+      options={[
+        { value: "TICKETS", label: "Tickets" },
+        { value: "ODOO", label: "Odoo" },
+      ]}
+      onChange={switchTo}
+    />
+  );
+}
+```
+
+### ✅ Global Error Handling
+
+`DomainException` instances that escape to the React root are bridged to native `Alert` dialogs automatically:
+
+```tsx
+import { installGlobalErrorHandler } from "@sincpro/mobile";
+
+// Call once before createAppShell
+installGlobalErrorHandler();
+```
+
+---
+
+## 🛠️ Creating a DomainModule
+
+A `DomainModule` is the primary building block. Here is how to create one from scratch:
+
+### Step 1 — Define the module class
+
+```tsx
 import { DomainModule } from "@sincpro/mobile/framework/domain_module";
 import type { Subscriber } from "@sincpro/mobile/domain/event_sourcing";
+import type { CronWorker } from "@sincpro/mobile/infrastructure/workers";
+import type { IMigration } from "@sincpro/mobile/domain/database";
 
-class VentasModule extends DomainModule {
-  readonly key = "VENTAS";
-  readonly name = "Ventas";
+export class TicketsModule extends DomainModule {
+  readonly key = "TICKETS"; // unique — used as the ui map key
+  readonly name = "Tickets"; // human-readable
+
+  override repositories() {
+    return {
+      ticketRepo: new TicketRepository(),
+      ticketLineRepo: new TicketLineRepository(),
+    };
+  }
+
+  override migrations(): IMigration[] {
+    return [CreateTicketsTable, CreateTicketLinesTable];
+  }
 
   override subscribers(): Subscriber[] {
-    return [];
+    return [TicketCreatedSubscriber, TicketPrintSubscriber, SyncTicketSubscriber];
+  }
+
+  override crons(): CronWorker[] {
+    return [SyncPendingTicketsCron];
+  }
+
+  // Preserved during logout wipe — ticket templates survive session reset
+  override persistOnReset(): string[] {
+    return ["ticket_templates", "ticket_categories"];
   }
 }
 
-const ventasModule = new VentasModule();
+export const ticketsModule = new TicketsModule();
+```
+
+### Step 2 — Module hook reference
+
+| Hook               | Returns                       | When it runs              | Can assume         |
+| ------------------ | ----------------------------- | ------------------------- | ------------------ |
+| `repositories()`   | `Record<string, IRepository>` | Kernel bootstrap          | Nothing yet        |
+| `migrations()`     | `IMigration[]`                | After repos registered    | Repos registered   |
+| `subscribers()`    | `Subscriber[]`                | After migrations          | DB schema ready    |
+| `crons()`          | `CronWorker[]`                | After subscribers         | Queue running      |
+| `persistOnReset()` | `string[]` table names        | On `unauthenticate(true)` | Called during wipe |
+
+All hooks return safe empty defaults. Override only what your domain needs.
+
+### Step 3 — Wire the module in the app shell
+
+```tsx
+export function createTicketsApp(): ComponentType {
+  // Register adapters before the shell boots
+  printerService.setDriver(PrinterAdapter);
+
+  return createAppShell({
+    theme:        createTheme(TICKETS_THEME),
+    darkTheme:    createTheme(TICKETS_DARK_THEME),
+    brandFont:    { files: { … }, families: { … } },
+    domains:      [odooModule, ticketsModule],
+    ui:           { [ticketsModule.key]: TicketsApp },
+    activeDomain: ticketsModule.key,
+    providers:    [ConfirmationProvider, ProcessToastProvider],
+    splashComponent: TicketsSplash,
+  });
+}
+```
+
+### Recommended project layout
+
+```
+sincpro_mobile_myapp/
+├── assets/
+│   └── fonts/               ← brand typeface files (.otf / .ttf)
+├── sincpro_mobile_myapp/
+│   ├── entrypoints/
+│   │   ├── main.tsx         ← DomainModule class + createMyApp()
+│   │   ├── cron/            ← CronWorker definitions
+│   │   ├── queue/           ← Subscriber definitions
+│   │   └── ui/
+│   │       ├── App.tsx      ← root screen component
+│   │       └── theme/
+│   │           └── tokens.ts ← ThemeTokens (light + dark)
+│   ├── adapters/            ← concrete port implementations (Printer, API, …)
+│   ├── domain/              ← entities, value objects, domain events, port interfaces
+│   ├── application/         ← use cases
+│   └── infrastructure/      ← repositories, remote clients
+└── app/
+    └── index.tsx            ← calls createMyApp(), exports default
+```
+
+---
+
+## ⚙️ AppShell Configuration
+
+`createAppShell(config)` is the single composition root. All infrastructure wires up from this one call.
+
+```tsx
+import { createAppShell, createTheme } from "@sincpro/mobile";
 
 export default createAppShell({
-  theme: createTheme({ primary: "#0EA5E9" }),
-  domains: [ventasModule],
-  ui: { [ventasModule.key]: VentasScreen },
-  activeDomain: ventasModule.key,
+  // ── Required ─────────────────────────────────────────────────────────────────
+  domains:      [odooModule, ticketsModule],  // modules to bootstrap (order matters for shared deps)
+  ui:           { [ticketsModule.key]: TicketsApp }, // domain key → screen component
+  activeDomain: ticketsModule.key,           // which UI to show on launch
+
+  // ── Theme ────────────────────────────────────────────────────────────────────
+  theme:     createTheme(TICKETS_THEME),
+  darkTheme: createTheme(TICKETS_DARK_THEME),
+
+  // ── Brand fonts ──────────────────────────────────────────────────────────────
+  brandFont: { files: { … }, families: { … } },
+
+  // ── Additional React context providers ───────────────────────────────────────
+  providers: [ConfirmationProvider, ProcessToastProvider],
+
+  // ── Splash screen ────────────────────────────────────────────────────────────
+  splashComponent: TicketsSplash,
+  splashDuration:  2000,  // ms minimum (default 2000)
+});
+```
+
+**Splash gate.** The splash stays visible until **all three** conditions are true simultaneously: domain bootstrap complete, brand fonts loaded by the native font registry, and minimum duration elapsed. This prevents flash-of-unstyled-content and loading flicker on any device speed.
+
+**Background domains.** Domains in `domains` without a matching key in `ui` are still fully bootstrapped — their queue, cron, repos, and migrations run normally. They just render no UI. This is how `@sincpro/mobile-odoo` works when included.
+
+**Provider wrap order.** `[A, B, C]` renders as `<A><B><C>{app}</C></B></A>`. The last item is the outermost wrapper.
+
+---
+
+## 🎨 Theme Configuration
+
+```tsx
+// entrypoints/ui/theme/tokens.ts
+import type { ThemeTokens } from "@sincpro/mobile-ui/theme/types";
+
+export const MY_THEME: ThemeTokens = {
+  name:      "my-app",
+  primary:   "#0B0B0B",  // buttons, active text
+  secondary: "#6B6963",  // muted neutral
+  accent:    "#00C357",  // CTA, focus rings, active states
+
+  bg: {
+    page:     "#FAFAFA",
+    card:     "#FFFFFF",
+    popover:  "#FFFFFF",
+    muted:    "#EDEBE6",
+    accent:   "#E6FFF2",  // selected surface (tinted)
+    hover:    "#F0F1EE",
+    disabled: "#F1F1EF",
+  },
+
+  text: {
+    primary:     "#0B0B0B",
+    secondary:   "#46443F",
+    accent:      "#006E2E",  // text on accent-tinted bg
+    inverse:     "#FFFFFF",
+    onPrimary:   "#FFFFFF",
+    onAccent:    "#FFFFFF",
+    // …full shape in @sincpro/mobile-ui README
+  },
+
+  border:  { default: "#E4E2DD", light: "#EFEDE8", strong: "#D1D5DB", focus: "#00C357" },
+  success: "#00C357", warning: "#FFB020", danger: "#FF4D1F", info: "#201DC4",
+  ring:    "#00C357",
+  input:   "#E4E2DD",
+  gradient: { primary: ["#1A1A1A", "#0B0B0B"], accent: ["#00A34A", "#00C357"] },
+  shadow:  { sm: { … }, md: { … }, lg: { … } },
+};
+```
+
+Pass both `theme` and `darkTheme` to `createAppShell`. The framework switches automatically with the system color scheme. `useCommon().colorScheme` exposes the current value and `setColorScheme()` lets the user override it manually (persisted to the settings table).
+
+---
+
+## 🔤 Brand Font Configuration
+
+The framework loads **only** the fonts you declare — nothing is assumed or loaded silently. Font files are owned by the app; the framework wires them into the DS typography roles.
+
+### The four semantic slots (aligned with the brand manual)
+
+| Slot      | Brand label | Purpose                          | DS default |
+| --------- | ----------- | -------------------------------- | ---------- |
+| `display` | `df`        | Titles, headings, hero text      | Inter      |
+| `body`    | `bf`        | Body, labels, buttons (13–15px)  | Inter      |
+| `caption` | `cf`        | Captions, overlines, metadata    | Fira Code  |
+| `mono`    | `mono`      | Amounts, SKU codes, numeric data | Fira Code  |
+
+Most apps only need to declare `display`. Omitting a slot keeps the DS default.
+
+```tsx
+import { FiraCode_400Regular, FiraCode_500Medium } from "@expo-google-fonts/fira-code";
+import {
+  Inter_300Light,
+  Inter_400Regular,
+  Inter_500Medium,
+  Inter_600SemiBold,
+  Inter_800ExtraBold,
+} from "@expo-google-fonts/inter";
+
+createAppShell({
+  brandFont: {
+    files: {
+      // df — Display (brand typeface, local .otf files)
+      "Satoshi-Regular": require("../../assets/fonts/Satoshi-Regular.otf"),
+      "Satoshi-Medium": require("../../assets/fonts/Satoshi-Medium.otf"),
+      "Satoshi-Bold": require("../../assets/fonts/Satoshi-Bold.otf"),
+      "Satoshi-Black": require("../../assets/fonts/Satoshi-Black.otf"),
+      // bf — Body (Inter via @expo-google-fonts/inter)
+      Inter_300Light,
+      Inter_400Regular,
+      Inter_500Medium,
+      Inter_600SemiBold,
+      Inter_800ExtraBold,
+      // cf + mono (Fira Code via @expo-google-fonts/fira-code)
+      FiraCode_400Regular,
+      FiraCode_500Medium,
+    },
+    families: {
+      display: {
+        regular: "Satoshi-Regular",
+        medium: "Satoshi-Medium",
+        bold: "Satoshi-Bold",
+        black: "Satoshi-Black",
+      },
+      body: {
+        light: "Inter_300Light",
+        regular: "Inter_400Regular",
+        medium: "Inter_500Medium",
+        semiBold: "Inter_600SemiBold",
+        extraBold: "Inter_800ExtraBold",
+      },
+      caption: { regular: "FiraCode_400Regular", medium: "FiraCode_500Medium" },
+      mono: { regular: "FiraCode_400Regular", medium: "FiraCode_500Medium" },
+    },
+  },
 });
 ```
 
-`createAppShell` arranca la infraestructura (migraciones, EventBus, cron, orchestrator), carga fuentes, aplica el tema (a `className` y `style`) y monta el `DomainSwitcher`.
+---
+
+## 📖 Public API
 
-## API pública
+### `createAppShell(config)` → `ComponentType`
 
-- `createAppShell(config)` — composition root de la app (theme, domains, ui, activeDomain, providers).
-- `DomainModule` — clase base abstracta de un dominio (`key`, `name`, `shared?`, `repositories()`, `migrations()`, `subscribers()`, `crons()`, `persistOnReset()`).
-- `createTheme(overrides?)` — theme tipado (defaults del framework + overrides parciales).
-- `createApp(config)` / `Kernel` / `orchestrator` — capa baja de composición (bootstrap sin UI).
-- `BaseModule` / `baseModule` — módulo común (COMMON) que el framework registra por defecto.
-- `CommonProvider` / `useCommon` — estado común (debug, geo, timezone, actividad de cola/cron).
-- `PlainLayout` / `TabNavigatorLayout` — layouts conectados a react-router.
-- `installGlobalErrorHandler()` — handler global (errores de dominio → Alert).
+Composition root. Returns a React component ready to export as the Expo entry point.
 
-## Subpaths
+### `DomainModule` (abstract class)
 
-Las primitivas y capas se importan por subpath, p. ej.:
+```tsx
+abstract class DomainModule {
+  abstract readonly key: string; // unique, used as ui map key
+  abstract readonly name: string; // human-readable label
+  readonly shared = false; // shared modules bootstrap first, cannot be disabled
+
+  repositories(): Record<string, object> {
+    return {};
+  }
+  migrations(): IMigration[] {
+    return [];
+  }
+  subscribers(): Subscriber[] {
+    return [];
+  }
+  crons(): CronWorker[] {
+    return [];
+  }
+  persistOnReset(): string[] {
+    return [];
+  }
+}
+```
+
+### `createTheme(overrides?)` → `ThemeTokens`
+
+Deep-merges partial overrides on top of the DS base theme.
+
+### `createApp(config?)` → `Promise<Kernel>`
+
+Low-level bootstrap without UI. Use for headless contexts (background workers, test harnesses).
+
+### `orchestrator`
+
+Singleton managing authentication state, domain activation, and queue/cron sync. Methods: `authenticateSession()`, `unauthenticateSession(cleanData?)`, `restoreSession()`, `enableDomain(key)`, `disableDomain(key)`, `isSessionAuthenticated()`.
+
+### `useCommon()` → `ICommonContext`
+
+```tsx
+const {
+  currentActivity,
+  lastError,
+  isProcessing,
+  dismiss,
+  colorScheme,
+  setColorScheme,
+  timezone,
+  updateTimezone,
+  hasGeoPermission,
+  requestGeoPermission,
+  debugMode,
+} = useCommon();
+```
+
+### `useDomainSwitcher()` → `{ activeDomain, switchTo }`
+
+```tsx
+const { activeDomain, switchTo } = useDomainSwitcher();
+switchTo("ODOO");
+```
+
+### `installGlobalErrorHandler()`
+
+Bridges `DomainException` to native `Alert`. Call once before `createAppShell`.
+
+### `baseModule` / `BaseModule`
+
+Built-in COMMON module. Always registered automatically — do not pass it to `domains`.
+
+---
+
+## 📦 Subpaths
 
 ```ts
+// Framework primitives
 import { DomainModule } from "@sincpro/mobile/framework/domain_module";
+import { orchestrator } from "@sincpro/mobile/framework/orchestrator";
+import { Kernel } from "@sincpro/mobile/framework/kernel";
+
+// Domain layer
 import type { Subscriber } from "@sincpro/mobile/domain/event_sourcing";
-import { setPrinterDriver } from "@sincpro/mobile/domain/print";
+import { Entity } from "@sincpro/mobile/domain/entity";
+import { RemoteEntity } from "@sincpro/mobile/domain/entity";
+import type { IMigration } from "@sincpro/mobile/domain/database";
+
+// Infrastructure
+import type { CronWorker } from "@sincpro/mobile/infrastructure/workers";
+import { EventBus } from "@sincpro/mobile/infrastructure/workers";
+
+// Services
+import { printerService } from "@sincpro/mobile/services/printer.service";
+import { deadLetterQueueUseCases } from "@sincpro/mobile/services/dlq.service";
+import { networkUseCases } from "@sincpro/mobile/services/network.service";
+
+// Adapters
+import { WebViewAdapter } from "@sincpro/mobile/adapters/webview";
+import { NetworkAdapter } from "@sincpro/mobile/adapters/network";
+import { GeoAdapter } from "@sincpro/mobile/adapters/geo";
+import { ReceiptExporterAdapter } from "@sincpro/mobile/adapters/receipt_exporter";
+
+// UI components (screens, events)
+import { PlainLayout } from "@sincpro/mobile/ui/screens/events";
 ```
 
-## Impresora (opcional)
+Full map in `package.json` under `exports`.
+
+---
+
+## 🔧 Development
 
-El core es agnóstico del hardware: define el puerto `IPrinterDriver` (`@sincpro/mobile/domain/print`). La app registra un driver concreto al bootstrap (vía `printerService.setDriver(...)`); si no registra ninguno, el driver Noop degrada con un warning.
+All tasks run through `make`:
 
-## Desarrollo
+| Command              | What it does                                           |
+| -------------------- | ------------------------------------------------------ |
+| `make build`         | `tsc` + `tsc-alias` → `dist/` (JS + type declarations) |
+| `make format`        | Auto-fix: ESLint + Prettier + type-check               |
+| `make verify-format` | CI gate — runs `format`, fails if any file changed     |
+| `make publish`       | Bump version + `npm publish`                           |
+
+**Local monorepo propagation** (no symlinks setup):
+
+```bash
+# After make build — copy dist to each consumer
+cp -r dist/* ../sincpro_mobile_tickets/node_modules/@sincpro/mobile/dist/
+cp -r dist/* ../sincpro_mobile_distribution/node_modules/@sincpro/mobile/dist/
+```
 
-Todo vía Makefile. Dos comandos de calidad: `make format` (auto-fix: eslint --fix + prettier + typecheck) y `make verify-format` (gate de CI: corre `format` y falla si quedó algo sin formatear/commitear — cubre lint + formato + tipos). Además `make build` (tsc + tsc-alias → `dist/`) y `make publish`. Detalle del workflow y guardrails en [`AGENTS.md`](AGENTS.md).
+Detailed workflow, naming conventions, architectural decisions, and AI guardrails: [`AGENTS.md`](AGENTS.md).