Design the entire CarBox home in Android Studio.

carBox().launchApp("com.spotify.music", CarBoxTarget.LEFT_PANEL);
carBox().launchApp("com.spotify.music", CarBoxTarget.RIGHT_PANEL);
carBox().launchApp("com.spotify.music", CarBoxTarget.SINGLE_PANEL);   // single-panel layout (launcher 1.96+)
carBox().launchApp("com.spotify.music", CarBoxTarget.FULLSCREEN);
carBox().launchApp("com.spotify.music", CarBoxTarget.PORTAL);   // launcher 1.80+

// PORTAL opens the app in a small floating window the user can freely
// drag, resize (bottom-right handle) and drop against a screen edge:
//   • left edge   → app becomes the left panel  (task moved, session kept)
//   • right edge  → app becomes the right panel (task moved, session kept)
//   • top edge    → app goes fullscreen         (task moved, session kept)
//   • bottom edge → app + Portal are closed
// The user must enable "CarBox Portal" in Launcher settings for the target
// to activate; when the toggle is OFF the launcher silently falls back to
// fullscreen so PORTAL never fails visibly for the theme.
// Two settings-side sliders let the user tune the initial window size and
// the DPI-scale of the app inside the window (default 50/50).
carBox().launchApp("com.google.android.youtube", CarBoxTarget.PORTAL);

carBox().openDrawer();          // app drawer
carBox().openPhone();           // phone / dialer
carBox().openContacts();        // contacts
carBox().openNotifications();   // notifications panel
carBox().openSettings();        // launcher settings
carBox().openAssistant();       // voice assistant
carBox().goHome();              // back to launcher home

// Starts a phone call on the paired Android smartphone through the CarBox
// Companion app. The AI-box has NO SIM: the call is dialed BY THE PHONE.
// numberOrName can be:
//   - a raw phone number (e.g. "+391234567890" or "1234567890")
//   - a contact name — the Companion looks it up in the phone's address book
//     and, if the contact has several numbers, prompts on the box to pick one.
// Requires the user to have paired a Companion (Bluetooth or LAN); the
// launcher shows a toast "Companion non connesso" if nothing is paired.
// Wraps LauncherActivity.apiCall(String) — in-process reflection when the
// theme runs as plugin, broadcast (THEME_COMMAND "call" + EXTRA_TEXT) as
// fallback. Never opens the local Android dialer.
carBox().callNumber("+391234567890");   // dial a number
carBox().callNumber("Mario Rossi");     // dial a contact by name

// Themes that pre-date the Bridge helper can call the API by hand via the
// same broadcast the SDK uses under the hood:
context.sendBroadcast(new Intent("com.ferra.carboxlauncher.action.THEME_COMMAND")
        .setPackage("com.ferra.carboxlauncher")
        .putExtra("command", "call")
        .putExtra("com.ferra.carboxlauncher.extra.TEXT", "+391234567890"));

// Fetch the contacts stored on the paired Android smartphone via Companion.
// Returns async (BT/LAN request); the callbacks fire on a worker thread —
// hop to the UI thread yourself before touching Views. Not on the classic
// broadcast bridge: needs in-process reflection (theme running as plugin).
// getCompanionContacts() returns false when the launcher predates the API
// or the theme is not in-process (preview mode) — treat that as "no data",
// falling back to the local ContactsContract if it fits your use case.
//
// JSON shape (matches the wire format used by PhoneActivity):
//   [ { "name": "Mario Rossi",
//       "numbers": [ { "number": "+391234567890", "label": "Mobile" }, ... ] },
//     ... ]
Handler ui = new Handler(Looper.getMainLooper());
boolean asked = carBox().getCompanionContacts(
    json -> ui.post(() -> {
        try {
            JSONArray arr = new JSONArray(json);
            for (int i = 0; i < arr.length(); i++) {
                JSONObject o = arr.getJSONObject(i);
                String name    = o.optString("name", "");
                JSONArray nums = o.optJSONArray("numbers");
                // … render your picker row per contact …
            }
        } catch (Throwable ignored) {}
    }),
    err  -> ui.post(() -> toast(err))   // "Companion non connesso", timeout, etc.
);
if (!asked) {
    // Launcher older than 1.88, or theme running standalone — no Companion.
}

// The launcher polls the paired phone battery via Companion every ~90s
// and caches the last value in SharedPreferences "cbx_phone_battery".
// Themes should read the cache — never hit Companion directly — so the
// UI stays fast and offline-tolerant. If the launcher pre-dates 1.97 the
// getters return -1/false silently: check level>=0 before showing anything.
//
// SharedPreferences keys inside "cbx_phone_battery":
//   level          int   0..100, -1 if never received
//   charging       bool  true when AC/USB/wireless
//   plug           str   "none" | "ac" | "usb" | "wireless"
//   temperature_c  float phone battery temperature (optional)
//   last_ts        long  System.currentTimeMillis of the last reading
//   last_try_ts    long  ts of last request attempt (whether successful)
//   state          str   "ok" | "unreach" | "nocfg" (last poll outcome)

// One-shot read (call in refresh loop or on-demand):
int  pct      = carBox().getPhoneBatteryLevel();     // 0..100, -1 if none
boolean charging = carBox().isPhoneCharging();
String  plug     = carBox().getPhonePlug();          // "none" | "ac" | "usb" | "wireless"
long    ageMs    = System.currentTimeMillis() - carBox().getPhoneBatteryLastTs();

// Live updates: register the broadcast to redraw on every poll (~90s):
BroadcastReceiver rx = new BroadcastReceiver() {
    @Override public void onReceive(Context c, Intent i) { refreshBatteryUi(); }
};
IntentFilter f = new IntentFilter(CarBoxThemeBridge.ACTION_PHONE_BATTERY_UPDATED);
if (Build.VERSION.SDK_INT >= 33)
    ctx.registerReceiver(rx, f, Context.RECEIVER_NOT_EXPORTED);
else
    ctx.registerReceiver(rx, f);
// …in onDetachedFromWindow: ctx.unregisterReceiver(rx);

// Alternative: read the prefs directly and listen with OnSharedPreferenceChange:
SharedPreferences bp = carBox().getPhoneBatteryPrefs();
bp.registerOnSharedPreferenceChangeListener((p, key) -> refreshBatteryUi());

// Force an immediate fetch (skip the timer) on user interaction — e.g. tap
// on a battery widget to get a fresh value instead of the cached one:
carBox().refreshPhoneBattery();

carBox().openCreativeMode();    // switch to creative mode
carBox().restartLauncher();     // restart the launcher process
carBox().reloadPanels();        // re-render dual-app panels

// Two launcher APIs are exposed for themes that want a "clean memory" or
// "close everything" button. They are NOT wrapped by the current Bridge
// SDK: call them via reflection on the LauncherActivity (in-process, same
// UID as the launcher when the theme runs as plugin). Both return an int
// with the number of packages killed.
//
// apiCleanMemory()   → closes background apps outside the launcher
//                      whitelist. Dual panels, the active theme plugin,
//                      the Portal window, the launcher itself, the user's
//                      Startup Apps and the manual whitelist stay alive.
// apiCloseAllApps()  → aggressive: closes EVERY user background app.
//                      Excludes only the launcher and base system
//                      processes; dual panels and the active theme are
//                      killed too.
Activity host = getActivity(); // hosted Activity of the launcher
int killed = 0;
try {
    java.lang.reflect.Method m = host.getClass().getMethod("apiCleanMemory");
    killed = (Integer) m.invoke(host);
} catch (Throwable ignored) { // launcher older than 1.87 → no-op }

// In creative mode the CreativeLayout hosts widgets and shows the "+" edit
// button only when edit mode is ON. A theme can bind long-press on its own
// creative icon to toggle the "+" without leaving creative — the pattern used
// by Dark Drive on its dock creativeButton.
boolean inCreative = carBox().isCreativeMode();   // query; false if unsupported
carBox().toggleEditMode();                        // no-op when NOT in creative

// Example: long-press on the theme's own "creative" icon toggles the "+"
// only when we are already in creative — short tap keeps the classic behaviour.
creativeIcon.setOnClickListener(v -> carBox().openCreativeMode());
creativeIcon.setOnLongClickListener(v -> {
    if (carBox().isCreativeMode()) carBox().toggleEditMode();
    return true; // consume the long-press even outside creative
});

// Legacy VD path only: reports the DualApp rect to CarBox.
// Plugin v2: skip this — the launcher inserts panels into getPanelHost().
carBox().reportPanelArea(new Rect(0, 0, 800, 480));

carBox().hidePanelHandles();
carBox().showPanelHandles();
carBox().setPanelHandlesVisible(false);
carBox().togglePanelHandles();

// Same behaviour as tapping the launcher's bottom handles.
// A second call restores the saved split ratio.
carBox().expandLeftPanel();
carBox().expandRightPanel();

// New in launcher 1.75+. Read the CURRENT left-panel fraction (0..1) so a
// theme can save "user pinned panels at 70/30" as part of a preset.
// Falls back to 0.5 if the launcher is older or the panels are not ready.
float ratio = carBox().getPanelSplitRatio();

// Restore the exact split when the user re-applies a saved preset.
// Range is clamped to [0.15, 0.85] on the launcher side (safety, no tiny panels).
// The launcher debounces rapid calls (120 ms) so rebuilding a whole preset in a loop is safe.
carBox().setPanelSplitRatio(0.7f);   // 70% left, 30% right

// Themes that need only ONE app panel (Android Auto style, dashboards, ecc.)
// can ask the launcher to hide the right panel + divider + all handles.
// The remaining LEFT panel expands to fill the whole panelHost.
//
// Two ways to declare it:
//
// 1) STATIC (manifest meta-data) — read at boot, applies before the panels
//    are even measured, so no 50/50 flash. Ideal when the theme is always
//    single-panel.
<meta-data android:name="carbox.theme.layout_mode" android:value="single" />

// 2) RUNTIME (bridge) — call in onHostAttached() or later. The preference
//    is persisted so the next boot honors it before your plugin is loaded.
carBox().setLayoutMode("single");   // pannello unico (LEFT full)
carBox().setLayoutMode("dual");     // default: LEFT + RIGHT + divider

// The launcher target "single" routes to the visible panel automatically
// (== LEFT in single mode, == LEFT in dual mode with right fallback).
carBox().launchApp("com.spotify.music", CarBoxTarget.SINGLE_PANEL);

// In single mode all native handles (barra inferiore + divider pill) sono
// nascoste dal launcher — il tema deve offrire le proprie affordance. Per
// aprire il dialog di configurazione del pannello (delay, orientazione,
// scala, picker app) usa:
carBox().openPanelSettings("single");   // ignora side in single mode
carBox().openPanelSettings("left");     // dual mode: LEFT
carBox().openPanelSettings("right");    // dual mode: RIGHT

// Sicuro: quando il tema è disattivato (utente cambia tema o disinstalla),
// il launcher forza automaticamente il ritorno a "dual" così il classic
// vede entrambi i pannelli. Puoi comunque essere esplicito nel detach.
@Override
protected void onThemeDetached() {
    carBox().setLayoutMode("dual");
}

// Dual-app panels sit above the launcher window and cover normal dialogs.
// Call setDialogMode(true) BEFORE showing a dialog and false when it dismisses:
// CarBox will move the panels aside without suspending the running apps.
carBox().setDialogMode(true);
dialog.setOnDismissListener(d -> carBox().setDialogMode(false));
dialog.show();

if (carBox().isHosted(this)) {
    // running inside CarBox: bridge commands are active
} else {
    // running standalone (preview mode): commands are no-ops
}