Delfino

Delfino is a TypeScript RPC bridge library that enables type-safe bidirectional communication between Volpe (an iframe-based reader) and its host applications (Farfalla and Fenice). The library encapsulates all Comlink complexity, providing simple, typed APIs for both sides of the communication.

Overview

Delfino provides:

• Type-safe RPC communication between iframe and host via Comlink
• Bidirectional message passing with automatic Message<T> wrapping
• Domain-based module organization (session, notes, content, playback, etc.)
• Security features including rate limiting and logging
• Singleton pattern for Volpe (hostBridge) and factory pattern for hosts (createClientBridge)
• MessageChannel-based communication for isolation and performance

Package Information

Property	Value
Package Name	@publicala/delfino
Current Version	1.1.1
Module Type	ESM ("type": "module")
Repository	https://gitlab.com/publicala/delfino.git
License	MIT (Proprietary - Publica.la)

Architecture

Communication Model

Delfino uses a bidirectional architecture where both sides share the same base class (BaseBridge) with different roles:

┌─────────────────────────────────────────────────────────────────────────┐
│                              COMMUNICATION FLOW                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   HOST (Farfalla/Fenice)              VOLPE (iframe)                     │
│   ══════════════════════              ══════════════                     │
│                                                                          │
│   ┌──────────────────────┐            ┌─────────────────────────────┐   │
│   │ ClientBridge         │            │ HostBridge                  │   │
│   │                      │            │                             │   │
│   │ Implements:          │            │ Implements:                 │   │
│   │   • Handlers         │◄───────────│   • Commands                │   │
│   │     (notes.store)    │  Volpe     │     (session.sessionExpired)│   │
│   │     (session.init)   │  APIs      │     (navigation.goBack)     │   │
│   │                      │  consume   │                             │   │
│   │                      │  handlers  │ Consumes (via APIs):        │   │
│   │ Calls:               │            │   • Handlers                │   │
│   │   • Commands         │───────────►│     notesAPI.store()        │   │
│   │     (goBack)         │  Host      │     sessionAPI.init()       │   │
│   │     (sessionExpired) │  calls     │                             │   │
│   │                      │  commands  │                             │   │
│   └──────────────────────┘            └─────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Naming Convention

The naming follows "bridge to communicate WITH X":

Bridge	Used By	Purpose
HostBridge	Volpe (iframe)	Communicate WITH the Host
ClientBridge	Host (Farfalla/Fenice)	Communicate WITH the Client (iframe)

Handlers vs Commands

Type	Implemented By	Consumed By	Direction
Handlers	Host (Farfalla/Fenice)	Volpe (via API classes)	Volpe → Host
Commands	Volpe	Host (Farfalla/Fenice)	Host → Volpe

Key distinction:

• Farfalla/Fenice creates Handler classes that implement the actual business logic (e.g., NotesHandlers with database operations)
• Volpe creates API classes that consume those Handlers through hostBridge (e.g., NotesAPI calls hostBridge.notes.store())

Technology Stack

Layer	Technology
Language	TypeScript 5.0+
RPC	Comlink 4.4.1
Build	Rollup 4.0+
Testing	Vitest 4.0+ (jsdom)
Linting	ESLint 9.39+
Formatting	Prettier 3.8+

Available Modules

Module	Handlers (Volpe → Host)	Commands (Host → Volpe)
session	initialize	sessionExpired
notes	list, store, update, delete	-
content	getContentStructure, searchContent	-
navigation	openLink, locationChanged, reachLastPage	goBack, goToPosition
playback	playTrack, pauseTrack, seekToPosition, playerStateChanged	externalPlayTrack, externalPauseTrack, externalSeekToPosition
reader	readerInitialized	reloadContent, getContentInfo
analytics	track	-
settings	update, cookiesAreDisabled	-
ui	close, share, copyToClipboard, exportText	-
integrations.ai	generate, feedback, listActions	-
integrations.dictionary	lookup	-
integrations.listen	synthesize	-
integrations.search	search	-
integrations.translate	translate	-

Security

Delfino provides two security presets:

Preset	Rate Limiting	Logging Level	Use Case
development	Disabled	debug	Local development
production	Enabled (50 req/30s)	warn	Production deployment

// Development: verbose logging, no rate limiting
createClientBridge(iframe, { security: 'development' });

// Production: rate limiting enabled, minimal logging
createClientBridge(iframe, { security: 'production' });

Version Synchronization

Volpe and Farfalla must use compatible versions of Delfino.

Rule: Volpe's Delfino version ≤ Farfalla's Delfino version

This ensures Volpe never calls methods that Farfalla does not implement.

Update Order:

1. Publish new Delfino version
2. Update Farfalla (implement new handlers)
3. Update Volpe (call new methods)

Related Systems

Delfino facilitates communication between:

• Volpe - Iframe-based content reader (PDF, EPUB, Audio)
• Farfalla - Main web application and backend API
• Fenice - Mobile and desktop reading applications

Development

For detailed architecture, integration guides, and local setup instructions, refer to the additional documentation sections in this project area.