Skip to content

@fkn/lib/packages

type AppConnectOptions = ConnectOptions & object;
optional payload?: unknown;

exposed to the package as ITS remote

optional raw?: boolean;

skip the osra handshake and hand back the untouched port - e.g. to transfer it into a worker and attach() there

optional signal?: AbortSignal;

type Connect = {
<T> (uri, options?): Promise<PackageConnection<T>>;
(uri, options): Promise<RawPackageConnection>;
};
<T>(uri, options?): Promise<PackageConnection<T>>;

T = unknown

string

ConnectOptions & object & object

Promise<PackageConnection<T>>

(uri, options): Promise<RawPackageConnection>;

string

ConnectOptions & object & object

Promise<RawPackageConnection>


type ConnectPayload = (info) => unknown;

produces the payload exposed to a connecting app - called once per incoming connection

IncomingConnectionInfo

unknown


type IncomingConnection<T> = IncomingConnectionInfo & PackageConnection<T>;

T = unknown


type IncomingConnectionInfo = object;
brokered: boolean;

True only when fkn.app’s broker made this connection (packages.connect), so from is the app the broker identified by its browser-set origin. False under packages.mount and for any other embedder. Worked out here from the origin of the message that carried the port, never read from the message. Key what a connection is allowed (a grant you stored, an app named to the person) to from only when this is true. A package built on a lib older than this field gets none, so test === true.

from: string;

The connecting app’s identity: its package uri when it runs on a sandbox origin, else its page origin. Proof of nothing unless brokered is true: under packages.mount, or in any page that frames this package’s url itself, the embedder writes whatever it likes here.

name: string;

this package’s npm name

protocol: string | null;

the contract tag the app passed to connect(), e.g. ‘stub-source@1’

uri: string;

this package’s normalized uri per the connecting app’s install record, e.g. ‘npm:@banou/stub-source-example’

version: string;

the exact version this frame runs - the pin is encoded into the sandbox origin, immutable per version


type MountedPackage<T> = PackageConnection<T> & object;
frame: HTMLIFrameElement;

the iframe you passed in, unchanged apart from its src

unmount: () => void;

blank the frame and settle closed; the element stays in your layout because it is yours

void

T = unknown


type MountOptions = AppConnectOptions & object;
iframe: HTMLIFrameElement;

the iframe the package is loaded into. YOU create it and YOU own it: its attributes, its styles and its place in your layout are yours, and mount only navigates it.

Set allow yourself for anything the package needs delegated, e.g. allow="fullscreen; autoplay". Permissions policy is not inherited, so a capability this frame is not granted cannot be recovered by the package or by anything it nests inside itself.

A sandbox on it must include allow-scripts and allow-same-origin, and needs nothing else: the package runs script, and keeps its own origin for its service worker and storage. mount refuses a sandbox without either, naming the token it lacks. Every other token is yours to grant: the package starts without allow-forms, allow-popups or any navigation token, and everything it frames inherits what this frame withholds. The FKN frame @fkn/lib keeps in this page must be unsandboxed, as it is unless this page runs in a sandboxed frame itself.


type PackageConnection<T> = object;

T = unknown

closed: Promise<void>;

settles when the package side of the connection dies (uninstall, reload, crash) - reconnect by calling connect() again

port: MessagePort;

the raw channel under remote, for direct messaging (osra envelopes ride it too - filter by your own message shape)

remote: Remote<T>;

the package’s exposed payload


type PackagesError = Error & object;
code: PackagesErrorCode;

type PackageView = object;
hide: () => void;

release this view; equivalent to packages.hide(uri, { element })

void

refresh: () => void;

force a re-measure, e.g. right after a layout change the tracker cannot observe

void


type RawPackageConnection = Omit<PackageConnection<never>, "remote">;

type ShowOptions = object;
optional element?: HTMLElement;

A placeholder the package frame is aligned to for as long as the view lives. The frame tracks its rect every animation frame, is clipped by its scrolling ancestors, and follows its border-radius, so it reads as inline content even though it renders in FKN’s overlay.

optional rect?: SurfaceRect;

an explicit viewport rect, for a caller that tracks placement itself

const connect: Connect;

Connect to an installed package. Throws a PackagesError with code ‘not-installed’ when it is not.

function attach<T>(
port,
payload?,
options?): Promise<Remote<T>>;

Run this end of an already-brokered connection port, e.g. after transferring it into a worker.

T = unknown

MessagePort

unknown

AbortSignal

Promise<Remote<T>>


function hide(uri, options?): Promise<void>;

Hide a package’s frame again, the counterpart to show(). Pass the same element to release only the view bound to it; with no element every view of this package is released. The connection is untouched, so the package can be shown again.

string

ShowOptions = {}

Promise<void>


function install(uri, options?): Promise<InstalledPackage | null>;

Install a package for this app behind an FKN-rendered confirm, or with { noConfirm: true } for a notice instead of a prompt. Resolves null when the user declines.

{ temporary: true } installs it for this tab only, with no install record: see InstallOptions.temporary. Throws a PackagesError with code ‘unsupported’, having installed nothing, on an fkn.app too old to hold that, so an app never ends up keeping what it asked not to keep.

string

InstallOptions

Promise<InstalledPackage | null>


function isVisible(): boolean;

True while a host app is showing this package’s frame. Packages start hidden.

boolean


function list(): Promise<InstalledPackage[]>;

The packages installed by this app, kept and temporary. A temporary one reads temporary: true.

Promise<InstalledPackage[]>


function mount<T>(uri, options): Promise<MountedPackage<T>>;

Load a package into an iframe of YOUR OWN and connect to it, instead of positioning a frame the broker owns and clipping the overlay to it the way show() does.

You pass the iframe, the same way cloud.attachFrame takes one. It lays out, scrolls, stacks and fullscreens with the rest of your page, there is no geometry to translate, and every attribute on it stays exactly as you set it: mount reads sandbox and allow to check the package can boot, then writes nothing but src. The package still gets its own origin and its own broker connection.

Grant capabilities through the iframe’s own allow, before calling this. Permissions policy is read at navigation and is not inherited, so it cannot be added afterwards on the frame handed back. A sandbox needs allow-scripts and allow-same-origin and nothing more (MountOptions.iframe).

Rejects with a PackagesError: ‘invalid’ for an iframe the package cannot start in, ‘unavailable’ with the reason the package’s frame gives when it fails to start, ‘timeout’ when it never answers.

Needs a package built against this version of the lib: an older one only accepts a port from fkn.app. The package reads brokered: false.

T = unknown

string

MountOptions

Promise<MountedPackage<T>>


function onConnect<T>(createPayload, handler?): object;

Serve connections from apps that installed this package. The first argument is called once per incoming connection with the connection info and returns the payload exposed to that app (its remote). The latest registration receives new connections; existing connections are unaffected.

T = unknown

ConnectPayload

(connection) => void

object

unsubscribe: () => void;

void


function onVisibilityChange(handler): object;

Observe whether a host app is showing this package’s frame, so it can render its UI only while on screen. The handler is called immediately with the current state, and on every change after.

(visible) => void

object

unsubscribe: () => void;

void


function pick(query, options?): Promise<PackageResult[]>;

FKN-rendered picker over the same search; resolves the user’s selection, already installed. [] on cancel.

PackageQuery

PickOptions

Promise<PackageResult[]>


function search(query): Promise<PackageResult[]>;

Search npm for FKN packages, e.g. search({ type: 'plugin', id: 'stub' }).

PackageQuery

Promise<PackageResult[]>


function show(uri, options): Promise<PackageView>;

Show an installed, connected package’s frame over this page, aligned to element (or an explicit rect). The package renders its own UI there; the app keeps the space in its own layout. Take it back down with hide() on the returned view, or with packages.hide(uri). Throws a PackagesError with code ‘not-installed’ when the package has not been connected by this app.

string

ShowOptions

Promise<PackageView>


function supportsTemporary(): Promise<boolean>;

Whether fkn.app can install a package temporarily, asked with no install attempted. False on an fkn.app older than InstallOptions.temporary; on an @fkn/lib older than it this export is undefined, so await packages.supportsTemporary?.() === true holds for both.

Promise<boolean>


function uninstall(uri): Promise<void>;

Uninstall a package from this app, kept or temporary; its frames and connections are torn down.

string

Promise<void>

Re-exports ConnectOptions


Re-exports InstalledPackage


Re-exports InstallOptions


Re-exports PackageQuery


Re-exports PackageResult


Re-exports PackagesErrorCode


Re-exports PickOptions


Re-exports Placement


Re-exports Radii


Re-exports SurfaceRect