pluginhost

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").
	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 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. Declaring it alone changes nothing: the host that
	// builds the plugin's [AssetServer] 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
}