Adapters

Adapters connect explicit Sercrod or application actions to capabilities that belong outside the core runtime. Sercrod owns host data, directive evaluation, update routing, and DOM rendering. Browser APIs, Capacitor/native bridges, project bridges, and build tools remain separate.

Runtime capability adapters live directly under dist/adapters/. Environment-specific behavior is selected inside each capability adapter where practical.

Registry

Sercrod.set_adapter("sercrod.filesystem", adapter);
Sercrod.use_adapter("file", "sercrod.filesystem");
Sercrod._get_adapter("file");

Adapters are also exposed through window.__Sercrod.adapters. Default role mappings live in window.__Sercrod.adapter_map.

Returning false from an adapter operation means that the request was not handled and the caller may continue to another backend or built-in fallback.

Backend order

Unless a capability documents a different order, adapters try:

1. A project-provided bridge.
2. A Capacitor or native bridge.
3. A browser implementation.
4. An explicit unsupported/no-op result.

This allows the same directive declaration to work in a browser and in a Capacitor application without pretending that browser and native permissions are identical.

Design contract

• Each adapter owns one external capability.
• Adapters do not own Sercrod rendering or application policy.
• Persistence, upload, playback, capture, navigation, and notification remain separate responsibilities.
• Permission requests that require user interaction remain explicit actions.
• A browser fallback must not silently replace a user-canceled native or browser prompt.
• Use diagnose() when platform availability or permission state needs to be inspected.
• Result placement uses *response. *into remains a compatibility alias for simple whole-result placement.

Capability layout

Current runtime capability adapters include:

dist/adapters/filesystem.js
dist/adapters/navigation.js
dist/adapters/camera.js
dist/adapters/clipboard.js
dist/adapters/media-playback.js
dist/adapters/audio-capture.js
dist/adapters/geolocation.js
dist/adapters/network-status.js
dist/adapters/diagnostics.js
dist/adapters/screen-state.js
dist/adapters/wake-lock.js
dist/adapters/haptics.js
dist/adapters/device-info.js
dist/adapters/share.js
dist/adapters/notification.js
dist/adapters/background-notification.js
dist/adapters/background-notification-runner.js
dist/adapters/foreground-notification.js
dist/adapters/push.js
dist/adapters/barcode.js
dist/adapters/upload.js

Ordinary capability adapters should not be split into parallel dist/adapters/browser/ and dist/adapters/capacitor/ trees. The common capability adapter chooses the available backend. Build-time Playwright support is a separate concern and may remain under dist/adapters/playwright/.

Filesystem

sercrod.filesystem is the default file role adapter. It supports JSON save/load operations and explicit file operations. It does not upload files.

For *save.file, Capacitor Filesystem is tried before the browser path. In a browser, Sercrod uses showSaveFilePicker() when available and falls back to a Blob-backed download when it is not. Canceling the picker cancels the action.

See *save and *load.

Navigation

sercrod.navigation.browser handles explicit *navigate actions and matching *page targets. It is not a global route table or link interceptor.

Device and media capabilities

The corresponding directive pages document their visible template surfaces:

• *camera
• *clipboard
• *audio-capture
• *geolocation
• *network-status
• *device-info
• *diagnostics
• *screen-state
• *wake-lock
• *haptics
• *share
• *barcode

Notifications

Local notification, remote push, and long-running platform-specific delivery are separate capabilities:

• *notification handles explicit local notifications.
• *push handles standard remote push registration and receive/action observation.
• *foreground-notification is an Android-specific self-hosted foreground-service path.

See Notification architecture and Push workflow before choosing an adapter.

Application boundary

Adapters provide capability access and normalized results. They do not decide:

• when an application should ask for permission;
• what business data should be persisted or uploaded;
• how authentication and authorization work;
• whether network requests should be retried;
• how WebSocket rooms or reconnection policies are designed;
• what UI should be displayed for unsupported capabilities.

Those decisions remain visible in the application and its Sercrod templates.