Packages

A package is an npm module that FKN loads on a sandbox origin of its own. Your app can install one, connect to it and show its UI without hosting any of its code. This page covers both sides of the contract: the host app (the app that installs and connects to a package) and the package that answers with onConnect.

The package side imports from @fkn/lib/packages. An app can use the same path or the packages namespace on the root. The examples call the two files app.ts and package.ts. The two sides talk over a MessagePort with a typed remote on each end.

The broker is the connection your app holds into FKN, reached through the broker frame, a hidden fkn.app iframe the library mounts. Every call the broker answers waits for it with no deadline (see connection and lifecycle). The steps between an app and a package are bounded, and the numbers are under timeouts and error codes.

Finding packages

packages.search(query) asks the npm registry for packages that carry FKN’s keywords:

app.ts

import { packages } from '@fkn/lib'

const results = await packages.search({ type: 'plugin', id: 'example', text: 'subtitles' })
results[0]?.uri // 'npm:@example/subtitles-plugin', the version-free uri
results[0]?.installed // true when this app already installed it

The query maps onto npm keywords, and only type is required:

Field	What it does
type	The package kind, the keyword fkn-type:<type>.
id	Your app’s scope, the keyword fkn-<type>--<id>. Optional.
origin	The package source, and 'npm' is the only one. Optional.
text	Free text in the registry query, cut to 128 characters. Optional.
size	The result count, 36 by default, clamped to 1 to 100. Optional.

type and id must match [a-z0-9][a-z0-9-]{0,31}, or the query is refused as 'invalid'. A result’s version comes from the search index, which can lag a publish by hours, so install resolves the version again from the registry.

packages.pick(query, options?) runs the same search behind a broker card, where the person selects and installs in one step:

app.ts

const picked = await packages.pick({ type: 'plugin', id: 'example' }, { title: 'Add a source', multiple: true })
picked.map(result => result.uri) // ['npm:@example/subtitles-plugin'], already installed, or [] when the person cancels

The card is headed Add packages. A title replaces that heading, rendered as text and cut to 120 characters, and multiple allows more than one selection. The resolved list holds only the packages the broker installed. A selection it could not resolve is left out, and the broker frame logs a warning in its own console.

Installing

packages.install(uri, options?) records a package for this app, pinned to a version:

app.ts

const installed = await packages.install('npm:@example/subtitles-plugin@1.4.2')
installed?.uri // 'npm:@example/subtitles-plugin', the version-free record
installed?.version // '1.4.2', the pin
installed // null when the person pressed Not now

The uri is npm:<name> with an optional @<version>, and options.version overrides it. Without either, the broker pins the package’s latest dist-tag. Only an exact version is accepted. A range such as ^1.2 is refused as 'invalid', and so is a version the registry does not know.

Unless you pass noConfirm: true, the broker asks “Install <name>@<version>?” with Install and Not now, and Not now resolves null. With noConfirm a notice, Package installed, shows for 6 seconds instead. A package this app already holds at the version you ask for, or when you ask for no version, comes back as the existing record with no card.

Two package prompts cannot be open at once. pick() and a confirming install() share one exclusive card, and a second call while it is open rejects with packages: another package prompt is already open, under 'unavailable'. Restoring a saved list with Promise.all therefore installs one package and rejects the rest.

Install one at a time, or pass noConfirm: true, whose notice sits outside the card. Keep the uri the record gives back: every other call takes the version-free form, and the pin lives in version. There is no update call, so install again with a version to move the pin.

packages.list() returns this app’s records, and packages.uninstall(uri) removes one:

app.ts

for (const pkg of await packages.list()) {
  pkg.uri // 'npm:@example/subtitles-plugin'
  pkg.version // '1.4.2', the pin
  pkg.installedAt // a millisecond epoch
}

await packages.uninstall('npm:@example/subtitles-plugin') // resolves, an unknown uri is not an error

Records are per installing app, so another app’s packages are invisible to yours. list() answers [] when the broker cannot identify the caller.

uninstall deletes the record, hides every view this app holds of the package and releases this app from its frame. The frame goes away only once the last app holding it lets go, and that is when every connection’s closed settles. The resolved promise is the signal that your uninstall took effect, never closed.

Connecting to a package

packages.connect(uri, options?) boots the package in a hidden frame the broker owns and hands you a connection to it. The type argument is the payload the package exposes, so import it from the package’s own file:

app.ts

import { packages } from '@fkn/lib'
import type { SourceApi } from './package'

const connection = await packages.connect<SourceApi>('npm:@example/subtitles-plugin', {
  protocol: 'example-source@1',
  payload: { appVersion: '1.2.0' }
})

await connection.remote.search('naruto') // ['result for naruto'], answered by the package
connection.closed.then(() => console.log('the package went away, connect() again to resume'))

Every function on that payload becomes an async one, and plain data stays itself, through osra’s Remote<T> (see TypeScript). Beside remote, the connection carries closed and port. closed settles when the package side dies (an uninstall, a reload, a crash). port is the raw MessagePort under remote, for your own messages.

Four options shape the connection. protocol is an opaque tag, cut to 64 characters and delivered to the package’s onConnect as info.protocol. It is the only versioning the connection has, so name your contract in it.

payload is what the package sees as its own remote. signal disconnects when aborted, which settles the package’s closed. raw: true hands back the untouched port with no handshake, so payload and signal do nothing beside it. Pass them to attach instead (see attaching in a worker).

The broker keeps one hidden frame per package and version, shared by every app connected to it. Connecting takes two stages. The package has to call onConnect within 30 seconds, and the handshake over the port then has to complete within another 30 seconds. A stage that runs out rejects as 'timeout'.

After a handshake timeout the frame is still alive, so closed does not settle for it and the retry is yours.

Every rejection the packages surface itself produces is a PackagesError, an Error with a code, and @fkn/lib/packages exports the type. Narrow on the code rather than on the class:

app.ts

import { packages } from '@fkn/lib'
import type { PackagesError } from '@fkn/lib/packages'

try {
  await packages.connect('npm:@example/subtitles-plugin')
} catch (error) {
  const { code, message } = error as PackagesError
  if (code === 'not-installed') console.warn('install it first:', message)
  else if (code === 'timeout') console.warn('the package never answered:', message)
  else throw error // a broker replaced mid-call lands here with no code at all
}

One rejection carries no code. Taking an update to the shell, the FKN surface that can update and reload the page, reloads the broker frame. A call in flight at that moment rejects with a plain FKN: the broker was replaced while this call was pending; retry it. code reads undefined there, and the else throw error above passes it on, so retry once (see a replaced broker).

Answering from the package

onConnect(createPayload, handler?) is how a package serves the apps that connect to it:

package.ts

import { onConnect } from '@fkn/lib/packages'

type HostApi = { appVersion: string }

const payload = { search: async (text: string) => [`result for ${text}`] }
export type SourceApi = typeof payload

const { unsubscribe } = onConnect<HostApi>(info => {
  if (info.protocol !== 'example-source@1') throw new Error(`unsupported protocol ${info.protocol}`)
  return payload
}, connection => {
  connection.from // 'https://example.org', the connecting app
  connection.remote.appVersion // '1.2.0', the app's payload, plain data so no await
  connection.closed.then(() => console.log('the app disconnected'))
}) // unsubscribe() stops new connections, the open ones keep running

createPayload runs once per incoming connection with that connection’s info. It may be async, and it returns what the app sees as its remote. A throw refuses the connection: the app rejects as 'unavailable' with your error’s message, and the package logs a warning. The optional handler then receives the same info plus remote, closed and port, the mirror of the app’s connection.

The info names the two ends:

Field	What it holds
from	The connecting app: its page origin, or its package uri when it is itself a package.
protocol	The tag the app passed to connect(), or null.
uri	This package’s version-free uri, as the app’s install record has it.
name	This package’s npm name.
version	The exact version this frame runs, encoded into its origin.

The whole info object is asserted by the document embedding the package: the broker under connect, and the app itself under mount. from and the rest are routing information, never proof of who is calling.

The first onConnect call announces the package as ready, so call it at boot. A package that never calls it never announces, and every app connecting to it times out with packages.connect: '<uri>' did not register a connection handler. Ports that arrive before the first registration are queued for it, and the latest registration receives new connections.

Note

onConnect listens only inside a frame. Opened as a top-level page for testing, the same code silently receives nothing.

A package’s account.info() and account.login() act on the host app’s connection. Its cloud.quota(), cloud.fs and cloud.fetch meter and store under the package’s own scope (see account and quota).

Publish the package

search and pick find a package by the keywords in its package.json: fkn, fkn-type:<type> for the type an app queries, and fkn-<type>--<id> for that app’s id. Publish it on npm with those three.

Its main is a self-contained browser ES module, because the loader injects it as a module script and resolves nothing. Import narrow subpaths such as @fkn/lib/packages rather than the root.

The root pulls in the socket surface, which needs Node stream shims a plain bundler configuration does not supply. A build from the root fails until they are added (see install). The recipe ship a package covers publishing.

Showing a package’s frame

packages.show(uri, { element }) places the package’s frame over your page, aligned to a placeholder you keep in your own layout:

app.ts

const uri = 'npm:@example/player-plugin'
const slot = document.querySelector<HTMLElement>('#player-slot')!
const connection = await packages.connect(uri, { protocol: 'example-player@1' }) // show() needs this live connection first
const view = await packages.show(uri, { element: slot })
connection.closed.then(() => view.hide()) // the package went away, so the view comes down with it

document.querySelector('#toggle-sidebar')!.addEventListener('click', () => view.refresh())
document.querySelector('#close')!.addEventListener('click', () => view.hide())

The frame tracks the placeholder every animation frame, clipped by every ancestor whose overflow is not visible, so it reads as inline content while it renders in FKN’s overlay. A still page pushes nothing. refresh() forces a re-measure after a layout change the tracker cannot see.

The frame follows the placeholder’s corner radii when every corner is a single pixel value. A percentage on any corner, or an elliptical radius written with a slash such as border-radius: 10px / 20px, drops the rounding on all four corners, so border-radius: 50% shows square corners.

show needs a live connect() by this app. An install record alone answers packages.show: '<id>' is not connected by this app - connect() before showing it, under 'not-installed'. With rect instead of element nothing tracks: refresh() re-reads the same object, so mutate it in place or call show() again. Passing neither is 'invalid', and a package that tries to show its own frame is 'denied'.

view.hide() and packages.hide(uri, { element }) release one view. packages.hide(uri) with no element releases every view this app holds of the package. The connection is untouched, so showing it again is cheap.

On the package side, isVisible() and onVisibilityChange(handler) say whether any app is showing the frame:

package.ts

import { isVisible, onVisibilityChange } from '@fkn/lib/packages'

isVisible() // false, a package starts hidden
onVisibilityChange(visible => { document.body.hidden = !visible }) // called at once with the current state, then on every change

The broker sends true when the first app shows the frame, false when the last one hides it, and true again when the package’s document reloads while an app is still showing it. Under mount the app sends true right after the port, since a frame in your layout is on screen by construction. A handler that throws is swallowed.

Mounting into your own iframe

packages.mount(uri, { iframe }) loads the package into an iframe you created instead of a frame the broker positions, so it lays out, scrolls and goes fullscreen with the rest of your page:

app.ts

const iframe = document.createElement('iframe')
iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin')
iframe.setAttribute('allow', 'fullscreen; autoplay; cross-origin-isolated')
document.querySelector('#player')!.append(iframe)

type PlayerApi = { play: (url: string) => Promise<boolean> }

const mounted = await packages.mount<PlayerApi>('npm:@example/player-plugin', { iframe, protocol: 'example-player@1' }) // needs an install record, no connect() before it
await mounted.remote.play('https://cdn.example.org/clip.mp4') // true, the package started playing
document.querySelector('#close')!.addEventListener('click', () => mounted.unmount()) // blanks the frame and settles closed, the element stays

The iframe is yours. mount writes src and nothing else, so its attributes, styles and place in your layout are what you set. It checks them first and refuses by name, as 'invalid', rather than failing at the boot deadline:

• the iframe is in the document, since a detached frame never navigates
• a sandbox attribute, if present, includes allow-scripts and allow-same-origin, since the package registers a service worker
• on a cross-origin isolated page, allow includes cross-origin-isolated, to hand it down

Grant everything else the package needs, such as fullscreen or autoplay, through allow before mounting. Permissions policy is read at navigation and cannot be added afterwards. The result is a connection plus frame, the element you passed, and an idempotent unmount() that never removes it.

mount needs an install record, and answers packages.mount: '<uri>' is not installed by this app without one. Unlike show it needs no connect() first: the mount is the connection. It requires a package built against a recent @fkn/lib, because an older one only accepts a port from fkn.app.

Mounting has the same two stages and the same errors as connect. The package sees from, uri and version from the broker’s record rather than the string you typed. A mount that fails either stage blanks your iframe and settles closed before it rejects, unlike connect, so a retry mounts again.

A boot failure under mount arrives as 'timeout', with the same message as a missing handler, rather than in the package’s own words. The package’s failure report is addressed to fkn.app and never reaches an iframe you mounted yourself.

Attaching in a worker

raw: true skips the handshake and gives you the untouched port. attach(port, payload?, options?) runs the app’s end of it wherever the port ends up:

app.ts

import type { Handoff } from './engine'
import { packages } from '@fkn/lib'

const engine = new Worker(new URL('./engine.ts', import.meta.url), { type: 'module' })

const { port, closed } = await packages.connect('npm:@example/subtitles-plugin', { raw: true, protocol: 'example-source@1' }) // the port before any handshake, and closed
engine.postMessage({ type: 'package-port', port } satisfies Handoff, [port])
closed.then(() => engine.postMessage({ type: 'package-gone' } satisfies Handoff)) // closed stays on the main thread, so the engine is told

The page hands the port to the worker, and closed stays behind on the main thread. The worker takes the port and runs the app’s end of the connection there:

engine.ts

import { attach } from '@fkn/lib/packages'
import type { SourceApi } from './package'

export type Handoff = { type: 'package-port', port: MessagePort } | { type: 'package-gone' }

self.addEventListener('message', async (event: MessageEvent<Handoff>) => {
  if (event.data.type === 'package-gone') return // the connection is over, the next port starts a new one
  const source = await attach<SourceApi>(event.data.port, { appVersion: '1.2.0' }) // the app's end of the connection, inside the worker
  await source.search('naruto') // ['result for naruto'], answered by the package
})

attach needs no window. Its options.signal ends the handshake before the 30 second guard does. It has no closed to watch, so a package that dies before the handshake reads as 'timeout'.

A realm is one JavaScript execution context, such as a window or a worker. The library gates a packages call on whether the realm has a window only for the calls that touch the DOM. onConnect, isVisible and onVisibilityChange are no-ops without a window, and show, hide and mount need one. The calls the broker answers, search, pick, install, list, uninstall and connect, are not gated on the realm by the library, and neither is attach.

In a worker those calls wait for the broker like every other call, so relay the worker from the page first (see workers). A realm with neither window nor self rejects them at once with packages: no FKN transport in this realm - use relayWorker to bridge workers, under 'unavailable'.

Messages between the two sides

Everything above rides on a handful of postMessage shapes, which you meet when you use port directly:

Message	Direction	What it says
fkn-packages-ready	package to its embedder	The package called onConnect, hand it ports.
fkn-packages-failed	the package’s frame to fkn.app	The package failed to boot, with a message. Never reaches an iframe you mounted yourself.
fkn-packages-port	embedder to package	One connection: from, protocol, uri, name, version and a port.
fkn-packages-visibility	embedder to package	visible: true or false.
fkn-packages-close	embedder to package	Every connection on this document is over.
fkn-packages-nack	package to app, over the port	The connection was refused before the handshake, with a message.
fkn-packages-disconnect	app to package, over the port	The app’s signal aborted.

The typed remote on each side is an osra connection over the same port, under the key fkn-packages-connection. When you read port yourself, give your messages a type of your own and return early on anything else. The osra envelopes and the two control messages then pass by untouched.

Timeouts and error codes

A PackagesError carries one of six codes. The one plain Error with none is FKN: the broker was replaced while this call was pending; retry it, described under connecting to a package:

Code	What happened
'invalid'	A malformed uri, query token or version range, a show with neither element nor rect, or a mount iframe the checks refused. The message names it.
'not-installed'	The uri has no record for this app, or was released while connecting, or show was called before connect.
'unaddressable'	npm:<name>@<version> does not fit the sandbox origin label, which holds roughly 40 characters of it. Use a shorter package name.
'timeout'	The package did not announce within 30 seconds, or did not complete the handshake within 30 seconds.
'unavailable'	The registry did not answer, another prompt was open, the package failed to boot, refused or closed the connection, your signal aborted, the record could not be written, the caller is not identified yet, or the realm has no transport.
'denied'	The platform disabled this package, or a package tried to show its own frame.

The two clocks are the boot wait, 30 seconds for fkn-packages-ready in connect and mount, and the handshake wait, 30 seconds in connect, mount and attach. A worst case connect() is therefore a minute, so an app that shows progress should race its own deadline.

A connection, a view and a mount each hold a busy token, one of the reasons a realm reports itself busy. shell.busyReasons() lists them as package connection (1), package view and mounted package (1) (see busy tokens). The exact signatures live in the generated reference for @fkn/lib/packages.

Errors you might see

The six rows a reader of this page meets most, each linked to its row on every error:

Message	What happened
packages: no FKN transport in this realm - use relayWorker to bridge workers	A packages.* call ran with neither window nor self. A worker has self, so there the call waits for the page to relay it (see workers).
packages: another package prompt is already open	A pick() or a confirming install() ran while another card was open. Wait for it to close, or install with noConfirm: true.
packages.<call>: '<uri>' is not installed by this app	connect or mount found no record for this app. Call install(uri) first, then pass the uri it gave back.
packages.connect: '<uri>' failed to boot: <failure>	The package’s frame reported why it could not start, in its own words after the colon.
packages.connect: '<uri>' did not register a connection handler	The package never called onConnect within the boot wait. Call it at boot.
packages.mount: the iframe's sandbox attribute must include <tokens>, or the package cannot start	The iframe carries a sandbox attribute without allow-scripts and allow-same-origin. Add both, or drop the attribute.

Every other message has its row on every error, and how to match one is on handling errors.

See also

• install a package and show its UI
• ship a package
• workers
• every error
• limits and timeouts