@fkn/lib/packages

Type Aliases

AppConnectOptions

type AppConnectOptions = ConnectOptions & object;

Type Declaration

payload?

optional payload?: unknown;

exposed to the package as ITS remote

raw?

optional raw?: boolean;

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

signal?

optional signal?: AbortSignal;

Connect

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

Call Signature

<T>(uri, options?): Promise<PackageConnection<T>>;

Type Parameters

T

T = unknown

Parameters

uri

string

options?

ConnectOptions & object & object

Returns

Promise<PackageConnection<T>>

Call Signature

(uri, options): Promise<RawPackageConnection>;

Parameters

uri

string

options

ConnectOptions & object & object

Returns

Promise<RawPackageConnection>

ConnectPayload

type ConnectPayload = (info) => unknown;

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

Parameters

info

IncomingConnectionInfo

Returns

unknown

IncomingConnection

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

Type Parameters

T

T = unknown

IncomingConnectionInfo

type IncomingConnectionInfo = object;

Properties

from

from: string;

the connecting app’s identity: its package uri when it runs on a sandbox origin, else its page origin

name

name: string;

this package’s npm name

protocol

protocol: string | null;

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

uri

uri: string;

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

version

version: string;

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

MountedPackage

type MountedPackage<T> = PackageConnection<T> & object;

Type Declaration

frame

frame: HTMLIFrameElement;

the iframe you passed in, unchanged apart from its src

unmount

unmount: () => void;

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

Returns

void

Type Parameters

T

T = unknown

MountOptions

type MountOptions = AppConnectOptions & object;

Type Declaration

iframe

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.

PackageConnection

type PackageConnection<T> = object;

Type Parameters

T

T = unknown

Properties

closed

closed: Promise<void>;

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

port

port: MessagePort;

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

remote

remote: Remote<T>;

the package’s exposed payload

PackagesError

type PackagesError = Error & object;

Type Declaration

code

code: PackagesErrorCode;

PackageView

type PackageView = object;

Properties

hide

hide: () => void;

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

Returns

void

refresh

refresh: () => void;

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

Returns

void

RawPackageConnection

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

ShowOptions

type ShowOptions = object;

Properties

element?

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.

rect?

optional rect?: SurfaceRect;

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

Variables

connect

const connect: Connect;

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

Functions

attach()

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.

Type Parameters

T

T = unknown

Parameters

port

MessagePort

payload?

unknown

options?

signal?

AbortSignal

Returns

Promise<Remote<T>>

hide()

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.

Parameters

uri

string

options?

ShowOptions = {}

Returns

Promise<void>

install()

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.

Parameters

uri

string

options?

InstallOptions

Returns

Promise<InstalledPackage | null>

isVisible()

function isVisible(): boolean;

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

Returns

boolean

list()

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

The packages installed by this app.

Returns

Promise<InstalledPackage[]>

mount()

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.

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

Type Parameters

T

T = unknown

Parameters

uri

string

options

MountOptions

Returns

Promise<MountedPackage<T>>

onConnect()

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.

Type Parameters

T

T = unknown

Parameters

createPayload

ConnectPayload

handler?

(connection) => void

Returns

object

unsubscribe

unsubscribe: () => void;

Returns

void

onVisibilityChange()

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.

Parameters

handler

(visible) => void

Returns

object

unsubscribe

unsubscribe: () => void;

Returns

void

pick()

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

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

Parameters

search()

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

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

Parameters

query

PackageQuery

Returns

Promise<PackageResult[]>

show()

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.