Native

​

What is the native bridge?

• NativePlugin is the versioned generic native plugin bridge.
• NativePlatform contains platform-wide helpers that are not plugin-specific.

​

Resolving native modules

import { native } from '@unbound-app/api';

const FileManager = native.getNativeModule('NativeFileModule', 'DCDFileManager', 'RTNFileManager');

​

Built-in handles

​

Reloading

import { native } from '@unbound-app/api';

await native.reload();

​

Platform helpers

import { native } from '@unbound-app/api';

const model = native.NativePlatform?.device.getDeviceModel();
const source = native.NativePlatform?.app.getAppSource();

​

Generic plugin bridge

import { native } from '@unbound-app/api';

export default {
	start(context) {
		const bridge = context?.native;
		if (!bridge) return;

		const messageClass = bridge.objc.getClass('DCDMessage');
		if (!messageClass) return;
		const message = bridge.objc.alloc(messageClass);
		bridge.objc.call(message, 'content');
	},
};

​

Objective-C operations

• Class lookup, allocation, selector calls, and superclass calls
• Ivar access and associated objects
• Registered structs, arrays, and data conversion
• Generic hooks

const { native } = pluginContext;
const cellName = 'DCDMessageTableViewCell';

const token = native.objc.hook(cellName, 'prepareForReuse', {
	before(context) {
		const viewModel = native.objc.getIvar(context.self, '_viewModel');
		if (viewModel) native.objc.call(viewModel, 'description');
	},
});

• Hook arguments are borrowed until the callback returns. Retain any value that needs to outlive the callback.
• original() is synchronous only when the callback runs on the hook thread. Calls from another thread fail closed to avoid deadlocks.
• Disposing a plugin context removes its hooks, associations, and bridge resources. Any later call through that context is rejected.

• Objective-C NSData results are returned as Uint8Array values.
• Native bridge failures are thrown, or rejected for asynchronous calls, as JavaScript errors with a stable code property on both iOS and Android. A coded native failure keeps its own code; other native runtime failures use the code NATIVE_BRIDGE_ERROR.
• Client-side negotiation errors have their own codes for unavailable bridges, missing capabilities, disposed scopes, and unsupported minimum API versions.

​

Raw FFI operations

const symbol = native.ffi.symbol('SomeLoadedSymbol');
if (symbol) {
	const value = native.ffi.call(
		symbol,
		{
			returnType: 'i32',
			args: ['pointer'],
		},
		pointer,
	);
}

• A signature takes at most 16 arguments, and no argument can be void.
• null or undefined passed as a cstring becomes a null pointer.
• Struct arguments can be { name, value } objects, plain field objects, or objc.struct values. Struct results have name and value properties, for example { name: 'timespec', value: { tv_sec: 1n, tv_nsec: 0n } }. On iOS, UIKit and Foundation structs come back as objc.struct values, so you can pass them straight to Objective-C calls.
• The registered structs are CGPoint, CGSize, CGVector, CGRect, NSRange, UIEdgeInsets, CGAffineTransform, timespec, and timeval.
• i64 and u64 results are BigInt values.

• Arbitrary memory access or dlopen
• Variadic calls or plugin-supplied native closures
• Unknown structs, vectors, unions, or bitfields

​

Fabric surfaces

const surface = native.fabric.mount(container, 'MessageLinkSurface', {
	surfaceId,
	targetMessageId,
});

const bounds = native.fabric.measure(container);
native.fabric.setSize(
	surface,
	{ width: bounds.width, height: 1 },
	{ width: bounds.width, height: 480 },
);
native.fabric.setFrame(surface, { x: 0, y: 120, width: bounds.width, height: 168 });
native.fabric.update(surface, { targetMessageId });
native.fabric.unmount(surface);

​

Capabilities and lifecycle

• Objective-C: native.objc.classes, native.objc.invoke, native.objc.ivars, native.objc.associations, native.objc.hooks
• FFI: native.ffi.symbols, native.ffi.call
• Fabric: native.fabric.mount (iOS only), native.fabric.async