@fkn/lib/packages
Type Aliases
Section titled “Type Aliases”AppConnectOptions
Section titled “AppConnectOptions”type AppConnectOptions = ConnectOptions & object;Type Declaration
Section titled “Type Declaration”payload?
Section titled “payload?”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
signal?
Section titled “signal?”optional signal?: AbortSignal;Connect
Section titled “Connect”type Connect = {<T> (uri, options?): Promise<PackageConnection<T>>; (uri, options): Promise<RawPackageConnection>;};Call Signature
Section titled “Call Signature”<T>(uri, options?): Promise<PackageConnection<T>>;Type Parameters
Section titled “Type Parameters”T = unknown
Parameters
Section titled “Parameters”string
options?
Section titled “options?”ConnectOptions & object & object
Returns
Section titled “Returns”Call Signature
Section titled “Call Signature”(uri, options): Promise<RawPackageConnection>;Parameters
Section titled “Parameters”string
options
Section titled “options”ConnectOptions & object & object
Returns
Section titled “Returns”ConnectPayload
Section titled “ConnectPayload”type ConnectPayload = (info) => unknown;produces the payload exposed to a connecting app - called once per incoming connection
Parameters
Section titled “Parameters”Returns
Section titled “Returns”unknown
IncomingConnection
Section titled “IncomingConnection”type IncomingConnection<T> = IncomingConnectionInfo & PackageConnection<T>;Type Parameters
Section titled “Type Parameters”T = unknown
IncomingConnectionInfo
Section titled “IncomingConnectionInfo”type IncomingConnectionInfo = object;Properties
Section titled “Properties”brokered
Section titled “brokered”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
Section titled “protocol”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
Section titled “version”version: string;the exact version this frame runs - the pin is encoded into the sandbox origin, immutable per version
MountedPackage
Section titled “MountedPackage”type MountedPackage<T> = PackageConnection<T> & object;Type Declaration
Section titled “Type Declaration”frame: HTMLIFrameElement;the iframe you passed in, unchanged apart from its src
unmount
Section titled “unmount”unmount: () => void;blank the frame and settle closed; the element stays in your layout because it is yours
Returns
Section titled “Returns”void
Type Parameters
Section titled “Type Parameters”T = unknown
MountOptions
Section titled “MountOptions”type MountOptions = AppConnectOptions & object;Type Declaration
Section titled “Type Declaration”iframe
Section titled “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.
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.
PackageConnection
Section titled “PackageConnection”type PackageConnection<T> = object;Type Parameters
Section titled “Type Parameters”T = unknown
Properties
Section titled “Properties”closed
Section titled “closed”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
Section titled “remote”remote: Remote<T>;the package’s exposed payload
PackagesError
Section titled “PackagesError”type PackagesError = Error & object;Type Declaration
Section titled “Type Declaration”code: PackagesErrorCode;PackageView
Section titled “PackageView”type PackageView = object;Properties
Section titled “Properties”hide: () => void;release this view; equivalent to packages.hide(uri, { element })
Returns
Section titled “Returns”void
refresh
Section titled “refresh”refresh: () => void;force a re-measure, e.g. right after a layout change the tracker cannot observe
Returns
Section titled “Returns”void
RawPackageConnection
Section titled “RawPackageConnection”type RawPackageConnection = Omit<PackageConnection<never>, "remote">;ShowOptions
Section titled “ShowOptions”type ShowOptions = object;Properties
Section titled “Properties”element?
Section titled “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.
optional rect?: SurfaceRect;an explicit viewport rect, for a caller that tracks placement itself
Variables
Section titled “Variables”connect
Section titled “connect”const connect: Connect;Connect to an installed package. Throws a PackagesError with code ‘not-installed’ when it is not.
Functions
Section titled “Functions”attach()
Section titled “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
Section titled “Type Parameters”T = unknown
Parameters
Section titled “Parameters”MessagePort
payload?
Section titled “payload?”unknown
options?
Section titled “options?”signal?
Section titled “signal?”AbortSignal
Returns
Section titled “Returns”Promise<Remote<T>>
hide()
Section titled “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
Section titled “Parameters”string
options?
Section titled “options?”ShowOptions = {}
Returns
Section titled “Returns”Promise<void>
install()
Section titled “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.
{ 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.
Parameters
Section titled “Parameters”string
options?
Section titled “options?”Returns
Section titled “Returns”Promise<InstalledPackage | null>
isVisible()
Section titled “isVisible()”function isVisible(): boolean;True while a host app is showing this package’s frame. Packages start hidden.
Returns
Section titled “Returns”boolean
list()
Section titled “list()”function list(): Promise<InstalledPackage[]>;The packages installed by this app, kept and temporary. A temporary one reads temporary: true.
Returns
Section titled “Returns”mount()
Section titled “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. 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.
Type Parameters
Section titled “Type Parameters”T = unknown
Parameters
Section titled “Parameters”string
options
Section titled “options”Returns
Section titled “Returns”onConnect()
Section titled “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
Section titled “Type Parameters”T = unknown
Parameters
Section titled “Parameters”createPayload
Section titled “createPayload”handler?
Section titled “handler?”(connection) => void
Returns
Section titled “Returns”object
unsubscribe
Section titled “unsubscribe”unsubscribe: () => void;Returns
Section titled “Returns”void
onVisibilityChange()
Section titled “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
Section titled “Parameters”handler
Section titled “handler”(visible) => void
Returns
Section titled “Returns”object
unsubscribe
Section titled “unsubscribe”unsubscribe: () => void;Returns
Section titled “Returns”void
pick()
Section titled “pick()”function pick(query, options?): Promise<PackageResult[]>;FKN-rendered picker over the same search; resolves the user’s selection, already installed. [] on cancel.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”search()
Section titled “search()”function search(query): Promise<PackageResult[]>;Search npm for FKN packages, e.g. search({ type: 'plugin', id: 'stub' }).
Parameters
Section titled “Parameters”Returns
Section titled “Returns”show()
Section titled “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.
Parameters
Section titled “Parameters”string
options
Section titled “options”Returns
Section titled “Returns”supportsTemporary()
Section titled “supportsTemporary()”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.
Returns
Section titled “Returns”Promise<boolean>
uninstall()
Section titled “uninstall()”function uninstall(uri): Promise<void>;Uninstall a package from this app, kept or temporary; its frames and connections are torn down.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
References
Section titled “References”ConnectOptions
Section titled “ConnectOptions”Re-exports ConnectOptions
InstalledPackage
Section titled “InstalledPackage”Re-exports InstalledPackage
InstallOptions
Section titled “InstallOptions”Re-exports InstallOptions
PackageQuery
Section titled “PackageQuery”Re-exports PackageQuery
PackageResult
Section titled “PackageResult”Re-exports PackageResult
PackagesErrorCode
Section titled “PackagesErrorCode”Re-exports PackagesErrorCode
PickOptions
Section titled “PickOptions”Re-exports PickOptions
Placement
Section titled “Placement”Re-exports Placement
Re-exports Radii
SurfaceRect
Section titled “SurfaceRect”Re-exports SurfaceRect