The manifest

A plugin's manifest is the ovvi key of its package.json. The app reads it before any of the plugin's code runs. So the chooser, ⌘K, Open With, the card's header row and the placeholder in herdr's TUI show at once, and the page only fills them in. There is no separate manifest file.

An example

A CSV table's package.json. The scripts and the dependencies are the template's (Build a plugin), left out here:

{
  "name": "csv-table",
  "version": "0.1.0",
  "description": "A CSV or TSV file as a table you can sort.",
  "keywords": ["csv", "table"],
  "ovvi": {
    "id": "csv-table",
    "name": "CSV Table",
    "api": 3,
    "entry": "dist/main.js",
    "icon": "tablecells",
    "opens": { "files": ["*.csv", "*.tsv", "public.comma-separated-values-text"] },
    "header": [
      { "id": "rows", "type": "text", "style": "dim" },
      { "type": "spacer" },
      { "id": "first-row", "type": "toggle", "symbol": "tablecells.badge.ellipsis",
        "title": "First Row Is Header", "value": true },
      { "id": "reload", "type": "button", "symbol": "arrow.clockwise", "title": "Reload" }
    ]
  }
}

Fields

From the package itself:

In the ovvi key:

• The app reads the manifest leniently. An unknown field is ignored, so a manifest written for a newer app still loads.
• A missing required field or a wrong value leaves the plugin out. The log and the plugin's cards name the field: ovvi.entry must be a built .js file in the package, ovvi.header.1 has the wrong type (Errors and logs).
• The checks beyond the types: the id's letters, a non-empty name and icon, api of 1 or more, entry a .js path with no / at the start and no .., opens.priority, a chooser only with folders, git or no opens, known header types with unique ids, a gap of 0 or more, digits only mono, a value on every segmented option, commands with ids unique among the commands and the header's controls, a file, edit or view menu and a key that reads as a chord, known handles, connect origins as above, and the settings' rules (Settings).

What a plugin opens

opens has one or more of these keys, and priority. The key sets what the label's argument holds, and the card's title.

• files is a list of patterns. Each is a name glob (*.csv, Makefile), case blind, or a uniform type identifier (public.image). A type matches its subtypes, as UTType.conforms(to:) says. A name the system does not know (a dynamic type, such as .rs) matches no type, only a glob or *.
• files and folders can go together: File Explorer opens both, with { "folders": true, "files": ["*"] }.
• urls is a list of globs for web addresses, case blind, where * also spans /. An ovvi.open of an http or https address with no plugin opens in a default plugin whose urls match it (a user's plugin before a default plugin), else in the browser.
• priority is "default" (the default) or "option". An option plugin opens a file only when the user picks it in Open With.

Which plugin opens a file

A link in a card, a double-click in File Explorer's tree and ovvi.open with no plugin open a file with its default plugin. The app picks it by the file's name alone, so a remote file is not read first:

1. Only default plugins whose patterns match take part.
2. The most specific pattern wins: an exact name (Makefile), then a glob (*.md), then a type, a subtype before its supertype (public.text before public.data), then *.
3. On a tie, a user's plugin wins over a default plugin. Then the lower id in alphabetical order wins.

File Explorer's * is the lowest rank. So a CSV plugin with *.csv takes .csv files from File Explorer, and any plugin with a pattern for a file wins over it. A path that ends in / opens in the first plugin with folders. An http or https address opens in the first plugin whose urls match it, else in the browser.

How it shows

• Open With lists the Mac's apps only on This Mac. The plugins show on every machine.
• A pick in Open With renames the pane to the other plugin's label with the same iid and argument. The card is made again as that plugin.

Header

header lists the controls of row 2, left to right (The card). The app draws them natively: the row is 32 pt tall in a pane (36 pt in a floating window), buttons are 22 × 22 pt in the card buttons' color, and the row ends where row 1 does. They show before the page loads, in a pane and in a floating window. The page changes them with ovvi.controls.set and hears them with ovvi.on("control") (Types). A click on a button, a toggle, a segment or a menu item gives the card the keyboard, as a click on its page does.

• Every control also takes hidden, enabled, label (what VoiceOver reads when the title says too little: "Push, 1 ahead") and gap.
• Spacing. Controls sit 6 pt apart. A control's gap sets the points before it: 0 joins icon buttons into a group (Preview's zoom buttons, Diff's Previous and Next), 2 sets them close.
• Width. A text with "digits": "mono" has monospaced digits, so a count (Preview's 3 of 12) keeps its width as it changes. Free space goes to a spacer or a field. With neither, it goes after the last control, so the row starts at the left.
• Ids. A control's id is unique in the plugin. It is also the end of its accessibility identifier: pane.<paneID>.<id>. A segment adds its title in lower case: pane.<paneID>.mode.source.
• Values. A toggle's value is a boolean, a path text's a list of strings, the others' a string. The app keeps each value in the card's state file under "controls" (State). A card loaded again, or shown again after it was dropped, gets the same values.
• A toggle, segments and a field change their value natively, then the page hears it. A menu pick only sends: an item can be an action, and the page sets the menu's value (Git's branch menu shows the branch once the switch ran). The same segment again, or a field set to its own text, sends nothing.
• Asks of the page. controls.set(id, { focus: true }) gives a plain field (not a path field) the keyboard (a page's ⌘F). controls.set(id, { refused: true }) shakes a path field, which keeps the typed path: the path names no place to go.
• One header for many places. A control that only some places use starts hidden: true in the manifest. The page shows its place's controls before it calls card.ready(). So a brand-new card draws only what the manifest shows until its page runs.
• No row. A plugin with no header and no history has one header row, in a pane and floating.

Commands

commands puts a card's commands in the menu bar and ⌘K, with their keys, only while that card has the keyboard. Elsewhere the item is gone, so it swallows no key (D93). The app owns the keys: each command is a row in Settings ▸ Keyboard Shortcuts, in a group named as the plugin, where the user can change or clear its key (Keyboard Shortcuts). The page never matches the key itself: it hears the pick.

"commands": [
  { "id": "lock-editing", "title": "Lock Editing", "menu": "view", "key": "cmd+e", "symbol": "lock",
    "keywords": ["markdown", "read", "edit", "unlock"] }
]

• menu is file, edit or view. keywords are more words that ⌘K finds the command by. key is the default key, a chord with cmd, ctrl or option (alt), plus shift if needed, and one key: a character or left, right, up, down, return, tab, space, escape, delete, plus (cmd+e, cmd+shift+k, ctrl+option+left). The user's key wins over it. A key that an app command already has is left off, the log says so once, and Settings marks the row.
• A pick sends { id } to ovvi.on("control"), as a header button does. ovvi.controls.set changes title, checked and enabled. A disabled command has no key, so ⌘E has its key only over Markdown.
• handles: ["save"] gives the card ⌘S (File ▸ Save). handles: ["find"] gives it ⌘F, ⌘G and ⇧⌘G. The page hears save, find, findNext and findPrevious. Git takes ⌘F only in a diff, not on its home.

Settings

settings lists up to 16 values that the user sets on the plugin's page in Settings ▸ Plugins. The app draws them from the manifest, saves them in settings.json (Plugin settings in settings.json), and gives them to the plugin's cards: ovvi.settings.get reads one, and the settings event brings each change at once (Types). A setting is one value for all machines.

"settings": [
  { "id": "first-row", "type": "toggle", "title": "First row is the header", "default": true },
  { "id": "delimiter", "type": "choice", "title": "Delimiter", "default": "auto",
    "options": [{ "value": "auto", "title": "Auto" }, { "value": "comma", "title": "Comma" },
      { "value": "tab", "title": "Tab" }] },
  { "id": "rows", "type": "number", "title": "Rows to read", "default": 10000,
    "min": 1000, "max": 100000, "step": 1000, "description": "Larger files open the first rows only." }
]

Every setting has these fields:

• A setting is a value. There is no secret type: no plugin can ask for a password or a token in Settings.
• A wrong setting leaves the plugin out, as a wrong header does. The log names the field: ovvi.settings.2.default does not fit the type, options or range, ovvi.settings.0.title must be 1 to 60 characters, ovvi.settings.1.id is taken, ovvi.settings has over 16 settings, ovvi.settings.0.description must be 0 to 200 characters.
• The page reads them, and never sets them: the user owns them. A card keeps its own choices in ovvi.state. The default plugins read ovvi.state.get()?.layout ?? ovvi.settings.get("diff-layout"), so a setting starts new cards and a card's own choice in its header wins.

Choices

The decisions are D96, D99, D103, D107 and D108 on the Decisions page.