pluginhost

type AssetOption func(*assetOptions)

type AssetServer struct {
	// contains filtered or unexported fields
}

type AssetSpec struct {
	// Name is the filename within the AssetServer's fs.FS (e.g. "editor.html").
	// The route is registered at prefix + "/" + Name.
	Name string

	// ContentType is the exact Content-Type header (e.g.
	// "text/html; charset=utf-8"). Optional: when empty it is derived from
	// Name's extension by [static.DetectFromName]. Set it only to override
	// that default, e.g. to serve a ".js" file as "application/json".
	ContentType string

	// Framed marks the assets that make up the sandboxed plugin frame (the
	// frame document and its sub-resources). Framed assets get the
	// framing/CORP/CSP relaxation GoFastr's global security middleware
	// otherwise blocks (DECISIONS.md "Phase 0 — DONE" gotcha #1); non-framed
	// host-page scripts (the broker / adapter) are served plain.
	Framed bool
}

type Attribute struct {
	Name  string
	Value string
}

type BrokerRegistration struct {
	Manifest Manifest                                 `json:"manifest"`
	Config   any                                      `json:"config,omitempty"`
	OnEvent  func(method string, params any, api any) `json:"-"`
}

type CacheProfile int

type ClientModule struct {
	// Name is the plugin name, also the data-fui-plugin attribute value the
	// mount marker carries and the generic broker dispatches on.
	Name string

	// Manifest describes the client module.
	Manifest Manifest

	// Assets is the (sub)filesystem holding the framed client assets
	// (editor.html / editor.js / editor.css). May be nil if the plugin serves
	// its assets itself.
	Assets fs.FS
}

type Field struct {
	Name  string
	Value string
}

type Manifest struct {
	// Entry is the frame document URL the broker loads into the iframe, e.g.
	// "/__gofastr/plugin/wysiwyg/editor.html". Required.
	Entry string `json:"entry"`

	// ScriptHash is an optional bundle hash used for cache-busting / SRI. v1
	// does not enforce it; the broker appends its own cache-buster.
	ScriptHash string `json:"scriptHash,omitempty"`

	// Isolation is the isolation model identifier. The v1 fixpoint is
	// [IsolationSandboxOpaque]. Empty defaults to it; any other value is
	// rejected by [Manifest.Validate].
	Isolation string `json:"isolation"`

	// Sandbox is the iframe sandbox token list. MUST contain "allow-scripts" and
	// MUST NOT contain "allow-same-origin" (enforced by [Manifest.Validate]).
	// Defaults to ["allow-scripts"] when empty.
	Sandbox []string `json:"sandbox"`

	// CSP lists opt-in Content-Security-Policy keywords appended to the framed
	// policy's script-src. It reaches the frame when the asset server is built
	// from the module — [ClientModule.AssetServer] threads it — because CSP is
	// the one manifest field applied as a response header rather than carried
	// on the manifest object to the mount. A host that instead calls
	// [NewAssetServer] directly must pass it through [AssetServer.WithCSP], or
	// the manifest validates, the frame still refuses WebAssembly, and nothing
	// reports why. The allowlist is closed and has exactly one member:
	// 'wasm-unsafe-eval', which lets a plugin compile WebAssembly inside the
	// sandboxed frame without granting
	// string eval ('unsafe-eval' stays forbidden) and without touching any
	// other directive — the frame keeps its opaque origin, sandbox
	// allow-scripts, and connect-src 'none', so a wasm engine still exchanges
	// data only over the postMessage bridge. Anything outside the allowlist
	// (a host source, 'unsafe-inline', 'unsafe-eval', '*', or a token
	// carrying ';', whitespace, or mismatched quotes — these values are
	// interpolated into a response header, where ';' could splice an
	// arbitrary directive such as re-enabled connect-src) is rejected by
	// [Manifest.Validate] and dropped at header assembly. Matching is EXACT,
	// byte-for-byte: unlike the HTML sandbox attribute the CSP header neither
	// case-folds nor whitespace-tokenises source expressions, so a variant
	// like 'WASM-UNSAFE-EVAL' grants nothing — and exact match rejects every
	// smuggle shape with the one comparison.
	CSP []string `json:"csp,omitempty"`

	// Capabilities is the default resource:verb grant set advertised to the
	// client in init.capabilities when the mount marker does not override it.
	Capabilities []string `json:"capabilities,omitempty"`

	// HostRequirements names browser features the HOST PAGE around the plugin
	// must be allowed to use, as "permissions-policy:<feature>" tokens (e.g.
	// "permissions-policy:camera" for a scanner whose host page captures and
	// whose sandboxed frame decodes). The frame itself is opaque-origin and
	// can never hold these permissions; this declares what the page embedding
	// it needs, so [CheckHostRequirements] can turn an unsatisfied token into
	// a boot-time warning instead of the runtime console error a user would
	// otherwise hit first. Validated against a closed feature registry.
	HostRequirements []string `json:"hostRequirements,omitempty"`

	// MinHeight is the initial iframe height before the first resize event.
	// Defaults to "240px" when empty.
	MinHeight string `json:"minHeight,omitempty"`

	// Schema is the interchange schema version bridged in init.schemaVersion
	// (e.g. "wysiwyg-v1").
	Schema string `json:"schema"`

	// Title is the iframe title attribute (accessibility). Defaults to
	// "Plugin" when empty.
	Title string `json:"title,omitempty"`
}

type MountConfig struct {
	// Plugin is the plugin name, the data-fui-plugin attribute the generic
	// broker dispatches on to find the registered adapter. Required.
	Plugin string

	// DocID is the persistence key (data-fui-plugin-docid). Defaults to
	// [DefaultDocID].
	DocID string

	// MinHeight is the initial iframe height (data-fui-plugin-minheight).
	// Defaults to [DefaultMinHeight].
	MinHeight string

	// Capabilities is an optional CSV grant override
	// (data-fui-plugin-capabilities). Empty ⇒ adapter manifest default.
	Capabilities string

	// Doc is an optional initial document JSON server-rendered into the marker
	// (data-fui-plugin-doc) for reload round-trip.
	Doc string

	// Fallback is server-rendered HTML placed inside the marker as the
	// pre-hydration state (wrapped in a div carrying
	// data-fui-plugin-fallback). The broker hides the iframe until the
	// frame reports ready, then hides the fallback — hidden, never
	// removed — and shows the frame; on bootError it swaps back, so a
	// plugin with a Go-side renderer (the chart plugin's SSR SVG)
	// degrades to its static output instead of an empty box, and works
	// with JavaScript off. Teardown restores it until SPA nav replaces
	// the marker.
	//
	// TRUST: this is render.HTML in the host page's own trust domain,
	// emitted verbatim like every render.HTML — the plugin's Go-side
	// Mount() builds it server-side; it never comes from the frame.
	Fallback render.HTML

	// Attributes are extra attributes appended to the marker (plugin-specific).
	Attributes []Attribute

	// Fields are hidden inputs emitted after the marker.
	Fields []Field
}

type WorkerCSP struct {
	// ScriptKeywords appends keywords to the worker policy's script-src.
	// Allowlist: 'unsafe-eval' (runtime compilation — ONNX Runtime glue,
	// asm.js builds, and the wasm gate on browsers that predate
	// 'wasm-unsafe-eval') and 'wasm-unsafe-eval' (WebAssembly compilation
	// only, the narrower grant when no string eval is needed). The base
	// 'self' is always present and cannot be removed.
	ScriptKeywords []string

	// ConnectSources widens the worker policy's connect-src from its
	// 'none' default. Allowlist: 'self', for fetching the wasm binary and
	// model bytes from the app's own origin. A CDN, wildcard, or remote
	// endpoint is refused: applications pin their runtimes same-origin
	// (the plugin-platform doc carries the delivery recipe), and this
	// server is not a remote-artifact proxy.
	ConnectSources []string

	// WASM appends 'wasm-unsafe-eval' — WebAssembly compilation without
	// string eval. Prefer it over ScriptKeywords when the worker only
	// compiles; add 'unsafe-eval' only when the runtime actually needs it.
	WASM bool
}