wire

type Action struct {
	ID      string  `json:"id"`
	Label   Text    `json:"label"`
	Icon    string  `json:"icon,omitempty"`
	Applies Applies `json:"applies"`
	View    string  `json:"view,omitempty"`
	Confirm Text    `json:"confirm,omitempty"`
	MinRole string  `json:"min_role,omitempty"` // viewer | editor | owner
	Danger  bool    `json:"danger,omitempty"`
	Output  Output  `json:"output"`
	Limits  Limits  `json:"limits,omitempty"`
	// Hidden keeps the action out of every menu: it is only ever started by
	// a surface (`job`) or a public page — the second half of a flow, not a
	// thing a person picks.
	Hidden bool `json:"hidden,omitempty"`
	// Requires names one of the manifest's `user_permissions` (its id): only
	// accounts that hold that permission see and run this action. Empty: the
	// action needs nothing beyond `min_role` and running apps at all.
	Requires string `json:"requires,omitempty"`
}

type ActionRunInput struct {
	JobID    string            `json:"job_id"`
	ActionID string            `json:"action_id"`
	Params   map[string]any    `json:"params,omitempty"`
	Inputs   []FileRef         `json:"inputs"`
	Output   Output            `json:"output"`
	Actor    Actor             `json:"actor"`
	Locale   string            `json:"locale,omitempty"`
	Settings map[string]string `json:"settings,omitempty"` // non-secret only
	Engines  map[string]bool   `json:"engines,omitempty"`
	// ShareMaxTTLDays: see CallContext.ShareMaxTTLDays. A job needs it for
	// the same reason a screen does — whatever it records about a link's
	// life (the request, the freeze beside it, the mail it sends) has to be
	// the life the link will actually get.
	ShareMaxTTLDays *int `json:"share_max_ttl_days,omitempty"`
}

type ActionRunOutput struct {
	OK      bool        `json:"ok"`
	Outputs []OutputRef `json:"outputs,omitempty"`
	Message Text        `json:"message,omitempty"`
	Surface *Surface    `json:"surface,omitempty"`
}

type Actor struct {
	ID    int64  `json:"id"`
	Email string `json:"email,omitempty"`
	Name  string `json:"name,omitempty"`
	Role  string `json:"role,omitempty"`
	// IP is the address the person's request came from, as filex's own
	// access log would write it (behind a trusted proxy, the forwarded
	// client). Set on a VIEW event — the screen somebody is looking at — and
	// empty on a job, which runs later and from nowhere in particular.
	//
	// ⚠ It exists for the same reason `data.page.visitor_ip` does on a
	// public page: an app that records WHO acted (the signing app's audit
	// trail, the IP line it can print under a signature) had that fact for
	// a stranger on a link and not for a signed-in person doing the same
	// thing — so the same box printed an address for one signer and "—" for
	// the next. Personal data: an app that records it must show it to the
	// person before it keeps it.
	IP string `json:"ip,omitempty"`
	// Permissions are the ids of THIS app's `user_permissions` the person
	// holds (filex 0.49.0 and later), decided exactly as filex decides them
	// at the door — an administrator holds every one. Set on a job
	// (`action_run`), a view event and an interface's call; absent on a
	// public page's event (nobody signed in) and on work nobody started.
	// Use Can.
	//
	// ⚠ Why an app needs it: filex refuses an action or a screen that
	// `requires` a permission before your code runs, but a hint on ANOTHER
	// screen ("…or Request signatures… to ask others") is drawn by you. The
	// signing app drew that hint for everybody, including a person the menu
	// no longer offered the action to. Say only what the reader can do.
	// It is a courtesy, not a gate — the door still decides.
	Permissions []string `json:"permissions,omitempty"`
}

type Applies struct {
	Kind  string   `json:"kind,omitempty"` // file | dir | any (default file)
	Ext   []string `json:"ext,omitempty"`  // lower-case, no dot
	Mime  []string `json:"mime,omitempty"` // exact or prefix glob "image/*"
	Multi bool     `json:"multi,omitempty"`
	Min   int      `json:"min,omitempty"`
	Max   int      `json:"max,omitempty"`
	// State narrows the offer to files on which THIS plugin keeps at least
	// one of the named state keys (`state_set`), NoState to files that
	// carry none of them. A signing app offers "Sign" only where a key
	// `pending` is set and "Request signatures" only where it is not. Keys
	// are the plugin's own; the listing exposes them as `<plugin>:<key>`.
	State   []string `json:"state,omitempty"`
	NoState []string `json:"no_state,omitempty"`
	// EngineExt adds extensions that are offered only while the named
	// engine is there and granted: `{"office": ["docx", "odt"]}` on top of
	// `ext: ["pdf"]` offers the action on a .docx exactly when the host can
	// turn one into a PDF (the office engine is the connected ONLYOFFICE;
	// `libreoffice`, its name before 0.50, reads the same). The host folds the list into Ext
	// before anybody sees the action (the explorer's menu, the run check),
	// so a client never evaluates it. It only ADDS to a non-empty ext/mime
	// list — an empty one already means "any file".
	//
	// ⚠⚠ Why (2026-09-21, a tester): "İmzala…" and "İmza iste…" were
	// offered on a .docx on an installation without LibreOffice, and the
	// click opened a page saying it is not a PDF and there is no LibreOffice
	// to convert it — while the Signatures screen itself said only PDFs can
	// be signed. An action that can never work must not be offered.
	EngineExt map[string][]string `json:"engine_ext,omitempty"`
	// Writable says the action can only be completed where its file can be
	// written, even though its own output is `none`: "Request signatures"
	// writes nothing now, but the flow it starts ends in writing the signed
	// document. filex hides such an action on a read-only storage (and
	// refuses it there with 409 read_only), exactly as it hides an action
	// whose output writes — instead of letting the app open a screen whose
	// only possible answer is "this cannot be done here". It needs the
	// files:write permission, and it counts as a write for the level the
	// caller needs (editor).
	Writable bool `json:"writable,omitempty"`
}

type CallContext struct {
	Inputs   []FileRef         `json:"inputs,omitempty"`
	Actor    *Actor            `json:"actor,omitempty"`
	Locale   string            `json:"locale,omitempty"`
	Settings map[string]string `json:"settings,omitempty"`
	Engines  map[string]bool   `json:"engines,omitempty"`
	// ShareMaxTTLDays is the longest life, in days, this installation gives
	// ANY new share link — the administrator's ceiling (Protection → share
	// links, `share.max_ttl_days`; 7 unless it was changed). 0 means no
	// ceiling; nil means the host did not say (older than v0.43.0) or this
	// app holds no `public_pages` grant and so opens no links.
	//
	// ⚠⚠ share_create clamps every link to the LOWEST of this, the page's own
	// `max_ttl_days` and 365. A screen that offers a longer life than that
	// promises something the link will not have: the signing app's wizard
	// said "links valid 14 days" while the link it opened lived 7, because
	// the ceiling was invisible from inside the app. Read it, and offer no
	// more than it allows.
	ShareMaxTTLDays *int `json:"share_max_ttl_days,omitempty"`
	// Home is where this person's results go by default when they cannot
	// go beside their source (Output.Elsewhere): the root of the first
	// storage, in the administrator's order, that the person may write.
	// Adapter-qualified (`depo://`); empty when they may write nowhere.
	Home string `json:"home,omitempty"`
}

type CoEditSpec struct {
	// Open: the app's `viewer` views open a file in its editing session -
	// whoever opens the same file with the app edits it with them. Needs an
	// interface (`ui`), a viewer view and `files:read`.
	Open bool `json:"open,omitempty"`
}

type Condition struct {
	Key    string   `json:"key"`
	Equals []string `json:"equals"`
}

type DescribeInput struct {
	HostVersion string `json:"host_version"`
	Locale      string `json:"locale,omitempty"`
}

type EncryptedFolders struct {
	// Open: the app's `viewer` views are offered on files in an unlocked
	// encrypted folder, and their `file.read` / `file.save` carry the
	// plaintext (FileInfo.plaintext). Needs an interface (`ui`), a viewer
	// view and `files:read`. Not in a vault and not for a single encrypted
	// file (`.fxe`) - filex 0.56 offers neither.
	Open bool `json:"open,omitempty"`
}

type Field struct {
	Key         string        `json:"key"`
	Type        string        `json:"type"` // string | password | int | bool | select | text
	Label       string        `json:"label"`
	Help        string        `json:"help,omitempty"`
	Required    bool          `json:"required,omitempty"`
	Secret      bool          `json:"secret,omitempty"`
	Default     any           `json:"default,omitempty"`
	Placeholder string        `json:"placeholder,omitempty"`
	Options     []FieldOption `json:"options,omitempty"`
	Min         *int          `json:"min,omitempty"`
	Max         *int          `json:"max,omitempty"`
	// Multi turns a `select` into a several-of choice. The value is then a
	// list of option values instead of one.
	Multi bool `json:"multi,omitempty"`
	// Style says how a `bool` is drawn: `switch` for an on/off setting a
	// person flips in passing, `choice` for a decision they must read
	// before answering (two buttons, Yes and No). Empty lets the client
	// decide, which it does by guessing — say it when the answer matters.
	Style string `json:"style,omitempty"`
	// ShowWhen hides the field until another field in the same form holds
	// one of the given values; RequiredWhen makes it required only then.
	// Both are re-checked by the host at submit: a value belonging to a
	// hidden field is dropped, and a required-when field that is empty
	// refuses the job. A form may not present a contradiction (a file name
	// asked for while the output is a new version of the same file).
	ShowWhen     *Condition `json:"show_when,omitempty"`
	RequiredWhen *Condition `json:"required_when,omitempty"`
	// I18n is the per-language spelling of Label, Help and Placeholder, when
	// they were written as {"en": …, "tr": …} instead of one string. Label,
	// Help and Placeholder then hold the English (or the only) spelling, so
	// code that reads them as strings keeps working, and the field is
	// written back out as the maps it arrived as.
	//
	// ⚠⚠ Why (2026-09-21, a tester): an app's settings were English inside
	// the Turkish admin panel — "Add a time stamp to every signature",
	// "Time-stamping authority" — because a manifest setting could only be
	// ONE string, while every other text an app shows (its name, its
	// actions, its screens) is a {en, tr} map the client already resolves.
	I18n *FieldI18n `json:"-"`
}

type FieldI18n struct {
	Label       Text
	Help        Text
	Placeholder Text
}

type FieldOption struct {
	Value     string `json:"value"`
	Label     string `json:"label"`
	LabelI18n Text   `json:"-"`
}

type FileRef struct {
	Ref     string `json:"ref"`
	Name    string `json:"name"`
	Size    int64  `json:"size"`
	Mime    string `json:"mime,omitempty"`
	PathRel string `json:"path_rel,omitempty"`
	// Path is the adapter-qualified form (`docs://reports/nda.pdf`) — what
	// the explorer navigates by and what a `pdf-fields`/`preview` node's
	// `src.path` takes. Filled by the host whenever the storage is known.
	Path string `json:"path,omitempty"`
	// ReadOnly says the file's storage takes no writes: no new version, no
	// file beside it. Filled by the host whenever the storage is known.
	//
	// ⚠⚠ Why an app needs to know BEFORE it writes (2026-09-21, a tester):
	// a signing request on a read-only storage was accepted and "sent" —
	// the file frozen, the signer notified — and the signer's answer then
	// failed with 409 read_only, for ever, because the request writes
	// nothing itself (its output mode is `none`) and the host's own
	// read-only refusal only guards jobs that write. Only the app knows
	// that the flow it starts ends in a write, so the app has to be told,
	// and has to refuse at the start with a sentence.
	ReadOnly bool `json:"read_only,omitempty"`
}

type HostError struct {
	Code    string `json:"code"`
	Message string `json:"message,omitempty"`
}

type JobRequest struct {
	ActionID string         `json:"action_id"`
	Params   map[string]any `json:"params,omitempty"`
	// Output, when set, replaces the action's manifest output for this one
	// job — a wizard's "same file as a new version / new file beside it /
	// custom name" choice. Mode is sibling | version | none; Name takes the
	// same {stem}/{ext}/{name} pattern as the manifest (a literal name works
	// too). Widening `none` to a writing mode is allowed only if the caller
	// holds editor on the inputs — the host re-checks at submit.
	Output *Output `json:"output,omitempty"`
}

type Limits struct {
	MemoryPages   int `json:"memory_pages,omitempty"`
	CallTimeoutS  int `json:"call_timeout_s,omitempty"`
	MaxInputBytes int `json:"max_input_bytes,omitempty"`
	TimeoutS      int `json:"timeout_s,omitempty"`
}

type Manifest struct {
	ManifestVersion int    `json:"manifest_version"`
	Name            string `json:"name"`
	Version         string `json:"version"`
	Label           Text   `json:"label"`
	Description     Text   `json:"description,omitempty"`
	Icon            string `json:"icon,omitempty"`
	Homepage        string `json:"homepage,omitempty"`
	// Filex is the range of filex versions the app works with, e.g.
	// ">=0.47.0" or ">=0.47.0 <0.60.0" (comparators joined by spaces must
	// all hold; alternatives are joined by "||"). Empty = any filex. filex
	// refuses to install or upgrade to a version whose range leaves the
	// running filex out, and its update check picks the newest version whose
	// range lets it in (docs/PLUGIN-KIT.md → Which filex it works with).
	// ⚠ filex before 0.47.0 does not know this field and refuses a manifest
	// that carries it; an app that must still install there says only
	// `min_filex`.
	Filex string `json:"filex,omitempty"`
	// MinFilex is the older, lower-bound-only form: "0.43.0" means
	// ">=0.43.0". Honoured together with Filex (both must hold).
	MinFilex    string   `json:"min_filex,omitempty"`
	Permissions []string `json:"permissions"`
	// Languages the plugin promises to speak. Every Text it returns must
	// carry all of them, or the host refuses it at install: a screen half in
	// one language is a bug the author should see before a person does.
	// Empty means ["en"].
	Languages []string `json:"languages,omitempty"`
	// UILocales lets a plugin add a language to FILEX ITSELF — the key is a
	// language tag, the value that language's strings by filex's own keys.
	// They join the language list the interface offers (public pages
	// included) and leave with the plugin. A missing key falls back to
	// English, as everywhere else.
	UILocales         map[string]map[string]string `json:"ui_locales,omitempty"`
	PermissionReasons map[string]Text              `json:"permission_reasons,omitempty"`
	Settings          []Field                      `json:"settings,omitempty"`
	Actions           []Action                     `json:"actions,omitempty"`
	// UserPermissions are what the app lets the administrator grant per role
	// and per person (app.<app>.<id>); actions and views name one in
	// `requires`. filex before 0.49.0 does not know this field and refuses
	// the manifest — declare it with `filex: ">=0.49.0"`.
	UserPermissions []UserPermission `json:"user_permissions,omitempty"`
	Views           []View           `json:"views,omitempty"`
	PublicPages     []PublicPage     `json:"public_pages,omitempty"`
	Limits          Limits           `json:"limits,omitempty"`
	Wasm            *WasmSource      `json:"wasm,omitempty"`
	// UI is the app's own interface (HTML/JS/CSS in a zip), served by filex
	// in a sandboxed frame. An app may have a module, an interface, or both.
	UI *UISpec `json:"ui,omitempty"`
	// NewDocuments are rows the app adds to filex's "New" menu: a file of
	// that kind, empty or made from a template in the interface's package,
	// opened in one of the app's `viewer` views. Each kind is a permission
	// (`ui-new:.<ext>`), derived like the interface's own.
	NewDocuments []NewDocument `json:"new_documents,omitempty"`
	// Messages are texts FILEX says on the app's behalf, long after the call
	// that caused them — today the reason beside a file lock ("signatures
	// are being collected"), shown in the admin panel, the details panel
	// and a refused rename, each in its READER's language. The app names
	// one by key when it locks (pluginkit.FileLockMessage); `{placeholders}`
	// are filled from the arguments it passes. Every declared language is
	// required, like every other Text.
	Messages map[string]Text `json:"messages,omitempty"`
	// Thumbnails says the app draws thumbnails of the kinds its Applies names
	// (filex 0.50.0 and later): its module answers the `thumbnail` export. Each
	// kind is a permission (`thumbnail:.<ext>` / `thumbnail:<type>`), derived
	// like the interface's, so an upgrade that draws one more kind is a new
	// grant. filex before 0.50.0 does not know this field and refuses the
	// manifest - declare it with `filex: ">=0.50.0"`.
	Thumbnails *ThumbnailSpec `json:"thumbnails,omitempty"`
	// EncryptedFolders says the app's interface edits files inside end-to-end
	// encrypted folders (filex 0.56.0, task #189). The server holds such a file
	// only as ciphertext and has no key to it, so filex never decrypts it on
	// the server: the person's browser decrypts the file with the folder key
	// it holds, hands the plaintext to the app's sandboxed frame only, and
	// encrypts what the app saves before it leaves the browser. Derived
	// permission `files:e2e-plaintext`, so the install review says it in its
	// own words. filex before 0.56.0 does not know this field and refuses the
	// manifest - declare it with `filex: ">=0.56.0"`.
	EncryptedFolders *EncryptedFolders `json:"encrypted_folders,omitempty"`
	// CoEdit says the app's interface edits a file together with other
	// people (filex 0.56.0, task #189): its `viewer` views open a file in
	// the file's editing session, through filex's relay (the bridge's
	// `coedit.*`). Derived permission `files:co-edit`, so the install review
	// says it in its own words. filex before 0.56.0 does not know this field
	// and refuses the manifest - declare it with `filex: ">=0.56.0"`.
	CoEdit *CoEditSpec `json:"co_edit,omitempty"`
}

type NewDocument struct {
	Ext      string `json:"ext"`
	Label    Text   `json:"label"`
	View     string `json:"view"`
	Template string `json:"template,omitempty"`
}

type Node struct {
	ID       string         `json:"id,omitempty"`
	Type     string         `json:"type"`
	Props    map[string]any `json:"props,omitempty"`
	Children []Node         `json:"children,omitempty"`
}

type OpenRequest struct {
	Path   string `json:"path"`
	Action string `json:"action,omitempty"`
	View   string `json:"view,omitempty"`
}

type Output struct {
	Mode string `json:"mode"`           // sibling | version | none | folder (per job)
	Name string `json:"name,omitempty"` // pattern: {stem}, {ext}, {name}
	// Elsewhere (manifest, with mode sibling) says the result may go into a
	// folder the PERSON chooses instead of beside its source: where the
	// source's storage is read-only, filex still offers the action and the
	// app asks where the result should go (a `file-chooser` with kind "dir",
	// starting at CallContext.Home), then answers the job with Output{Mode:
	// "folder", Dir: <the chosen folder>}. filex checks that folder — the
	// storage, the person's level on it, locks and filex's own folders —
	// before the job is queued and again when the file is written.
	Elsewhere bool `json:"elsewhere,omitempty"`
	// Dir is the chosen folder for mode "folder", adapter-qualified
	// (`docs://reports`). Only a JobRequest carries it.
	Dir string `json:"dir,omitempty"`
}

type OutputRef struct {
	Ref  string `json:"ref"`
	Name string `json:"name"`
}

type PagePurpose struct {
	// Label names the kind of link in a list: "Signing request".
	Label Text `json:"label"`
	// Revoke is said before the link is revoked, plainly: "Revoking this
	// link cancels the signing request."
	Revoke Text `json:"revoke,omitempty"`
	// Section is the section of the app's `home` view the row opens
	// (Surface.Sections); empty opens the home view as it comes.
	Section string `json:"section,omitempty"`
}

type PublicPage struct {
	ID             string `json:"id"`
	Label          Text   `json:"label"`
	PIN            string `json:"pin,omitempty"` // optional | required | none
	DefaultTTLDays int    `json:"default_ttl_days,omitempty"`
	MaxTTLDays     int    `json:"max_ttl_days,omitempty"`
	// Purpose says what a link of this page IS, for the person who sees it
	// in a list of links (My shares, the admin's Shares): it belongs to
	// something the app keeps, ending it ends that, and there is a place in
	// the app that shows it. Optional; without it a link lists as a share.
	Purpose *PagePurpose `json:"purpose,omitempty"`
}

type ScheduleItem struct {
	// Key is the app's own name for this piece of work, and the reason a
	// restart cannot run it twice: the host keeps at most one item per
	// (app, key), so naming the same key again moves the item rather than
	// adding a second one. A signing app keys by envelope
	// (`expire:7f3a…`). 1–64 characters of [A-Za-z0-9] plus `_.:@-`.
	Key string `json:"key"`
	// DueAt is when the work runs, to the minute (to the second, in fact).
	// A time already past runs at once; a time beyond WindowEnd is not
	// scheduled.
	DueAt time.Time `json:"due_at"`
	// ActionID is the app's action to run. It must exist in the manifest
	// and not be switched off by the administrator.
	ActionID string `json:"action_id"`
	// Paths are the files the job runs on, adapter-qualified
	// (`docs://reports/nda.pdf`) — the spelling `state_list` answers with.
	// At least one, at most MaxPaths, all on the same storage.
	Paths  []string       `json:"paths"`
	Params map[string]any `json:"params,omitempty"`
}

type Section struct {
	ID    string `json:"id"`
	Label Text   `json:"label"`
	// Count is drawn beside the label (a number of rows waiting there);
	// nil draws none.
	Count *int `json:"count,omitempty"`
}

type Surface struct {
	Title   Text            `json:"title,omitempty"`
	Size    string          `json:"size,omitempty"`
	State   map[string]any  `json:"state,omitempty"`
	Nodes   []Node          `json:"nodes"`
	Actions []SurfaceAction `json:"actions,omitempty"`
	Toast   Text            `json:"toast,omitempty"`
	Done    bool            `json:"done,omitempty"`
	Job     *JobRequest     `json:"job,omitempty"`
	Errors  map[string]Text `json:"errors,omitempty"`
	// Open sends the person to a FILE — the one thing a screen could not do
	// before. A home screen lists documents; a row has to be able to open
	// the one that was clicked, and open it on the right screen. The host
	// checks the path and the target before the answer leaves.
	Open *OpenRequest `json:"open,omitempty"`

	// Sections turn a `home` screen into a page with a MENU: one entry per
	// section, the frame drawing the menu and the plugin drawing whichever
	// section is open. Section says which one this surface is.
	//
	// ⚠⚠ Why the frame and not a node. The owner, 2026-09-21: the
	// Signatures screen should be "its own page … each in a separate menu",
	// with the browser's Back button working and a notification landing on
	// the right section. A node can draw tabs, but only the FRAME owns the
	// address bar: it keeps the open section in the URL (`?section=`), so
	// Back walks the sections and a link can name one. Opening a view with a
	// section in its address hands the plugin `data.section` on the `open`
	// event; everything after that is an ordinary conversation.
	Sections []Section `json:"sections,omitempty"`
	Section  string    `json:"section,omitempty"`
}

type SurfaceAction struct {
	ID       string `json:"id"`
	Label    Text   `json:"label"`
	Primary  bool   `json:"primary,omitempty"`
	Danger   bool   `json:"danger,omitempty"`
	Disabled bool   `json:"disabled,omitempty"`
}

type Text map[string]string

type ThumbnailInput struct {
	File FileRef `json:"file"`
	// Ext is the file name's extension, lower-case, no dot ("" for none).
	Ext string `json:"ext,omitempty"`
	// MaxWidth / MaxHeight are the box filex shows a thumbnail in. Drawing
	// larger is wasted: filex scales the answer down to fit.
	MaxWidth  int `json:"max_width"`
	MaxHeight int `json:"max_height"`
	// MaxOutputBytes is the most the answer's image may weigh.
	MaxOutputBytes int `json:"max_output_bytes"`
	// Locale is the instance's default language (a thumbnail is the same
	// picture for everybody).
	Locale   string            `json:"locale,omitempty"`
	Settings map[string]string `json:"settings,omitempty"` // non-secret only
}

type ThumbnailOutput struct {
	Image []byte `json:"image"`
}

type ThumbnailSpec struct {
	Applies Applies `json:"applies"`
}

type TickInput struct {
	// Now is the host's clock when the wake-up fired, in UTC.
	Now time.Time `json:"now"`
	// WindowStart and WindowEnd bound the due times this answer may name.
	// WindowStart equals Now; WindowEnd is the next hourly boundary, which
	// is when the next wake-up comes. An item due outside the window is not
	// scheduled and no error is raised — say it again at the wake-up whose
	// window contains it. After a restart at 03:37 the window is 03:37 to
	// 04:00, so it is shorter than an hour and the app is told so.
	WindowStart time.Time `json:"window_start"`
	WindowEnd   time.Time `json:"window_end"`
	// MaxItems is how many items this answer may carry. Extra ones are
	// dropped (the app's log says how many), so put the urgent ones first.
	MaxItems int `json:"max_items"`
	// MaxPaths is how many files one item may name.
	MaxPaths int               `json:"max_paths"`
	Locale   string            `json:"locale,omitempty"`
	Settings map[string]string `json:"settings,omitempty"` // non-secret only
	Engines  map[string]bool   `json:"engines,omitempty"`
}

type TickOutput struct {
	Items []ScheduleItem `json:"items,omitempty"`
	// Note is a line for the app's log in the admin panel — what this
	// wake-up decided, in the app's own words. It is not shown to anyone
	// else; there is nobody there.
	Note Text `json:"note,omitempty"`
}

type UIBundle struct {
	URL    string `json:"url,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
}

type UICallInput struct {
	ViewID  string          `json:"view_id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
	Context CallContext     `json:"context"`
}

type UICallOutput struct {
	Result any  `json:"result,omitempty"`
	Error  Text `json:"error,omitempty"`
}

type UIExternal struct {
	URL string `json:"url"`
	// As is what the file is: style | font | img | media. Never script, never
	// connect.
	As     string `json:"as"`
	SHA256 string `json:"sha256,omitempty"`
	Reason Text   `json:"reason,omitempty"`
}

type UISpec struct {
	// Bundle is the zip of the interface's files.
	Bundle UIBundle `json:"bundle"`
	// CSP names the exceptions to the interface's script policy:
	// "unsafe-eval" and "wasm-unsafe-eval". Each is a permission.
	CSP []string `json:"csp,omitempty"`
	// External are the addresses outside the package the interface loads.
	External []UIExternal `json:"external,omitempty"`
	// PackageFetch lets the interface READ its own package with fetch/XHR
	// (an editor that loads its stencils or translations at run time, as
	// draw.io does). Only this version's files: connect-src and the
	// Connection-Allowlist name the package's own path and nothing else. A
	// permission (`ui:package-fetch`), derived like the rest of this block.
	PackageFetch bool `json:"package_fetch,omitempty"`
	// Download lets the interface hand the person a file to keep on their
	// own disk (`ui.download` in the SDK): through filex, each time on the
	// person's gesture or their yes, never over the limit. A permission
	// (`ui:download`), derived like the rest of this block.
	Download bool `json:"download,omitempty"`
	// FramePackage lets the interface open pages of its OWN package in
	// frames of its own (an editor that puts the document in a frame, as
	// ONLYOFFICE's DocsAPI does). Only this version's pages: frame-src and
	// child-src name the package's own path and nothing else, and every
	// such page is served under the same policy and sandbox - an opaque
	// origin of its own, no storage, no connection the interface itself is
	// not granted. The bridge stays with
	// the frame filex drew; an inner frame talks to it with postMessage. A
	// permission (`ui:frame-package`), derived like the rest of this block.
	// filex 0.55 and later; an older filex refuses the field.
	FramePackage bool `json:"frame_package,omitempty"`
	// ConnectBlob lets the interface read `blob:` addresses it made itself
	// with fetch/XHR (a document it unpacked in memory, loaded by an editor
	// that only reads from an address): `blob:` in connect-src. A `blob:`
	// address is the page's own memory and reaches no server. A permission
	// (`ui:connect-blob`), derived like the rest of this block. filex 0.55
	// and later; an older filex refuses the field.
	ConnectBlob bool `json:"connect_blob,omitempty"`
	// Print lets the interface hand filex a PDF to print (`ui.print`): a
	// sandboxed frame may not open the browser's print dialog, so filex
	// prints the PDF from its own page, on the person's gesture in the
	// interface or their yes. A permission (`ui:print`), derived like the
	// rest of this block - the same kind as Download, since the print
	// dialog can save the PDF too. filex 0.55 and later; an older filex
	// refuses the field.
	Print bool `json:"print,omitempty"`
}

type UserPermission struct {
	ID          string `json:"id"`
	Label       Text   `json:"label"`
	Description Text   `json:"description,omitempty"`
	// Default is who holds it until the administrator decides: `viewer`
	// (every account), `user` (accounts that can change files — the usual
	// choice) or `admin` (administrators only, until granted).
	Default string `json:"default"`
}

type View struct {
	ID        string  `json:"id"`
	Placement string  `json:"placement"` // modal | page | inspector | home | viewer
	Label     Text    `json:"label"`
	Applies   Applies `json:"applies,omitempty"`
	Size      string  `json:"size,omitempty"`
	// UI is the bundle file this view opens ("index.html", "editor/main.html"):
	// the view is the app's own interface, served by filex in a sandboxed
	// frame (docs/APP-PLUGINS-API.md → An app's own interface). Empty: the
	// view is a Surface the module draws.
	UI string `json:"ui,omitempty"`
	// Requires: as Action.Requires — the view (and every job it starts) is
	// refused to an account without that user permission.
	Requires string `json:"requires,omitempty"`
}

type ViewEventInput struct {
	ViewID   string         `json:"view_id"`
	Event    string         `json:"event"` // open | change | submit | action
	ActionID string         `json:"action_id,omitempty"`
	State    map[string]any `json:"state,omitempty"`
	Data     map[string]any `json:"data,omitempty"`
	Context  CallContext    `json:"context"`
}

type WasmSource struct {
	URL    string `json:"url,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
}