@wildwinter/app-shell 0.57.0 → 0.58.0

package/dist/view-protocol.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/view-protocol.ts"],"names":[],"mappings":";;;AAgBO,IAAM,QAAA,GAAW;AAwKjB,IAAM,iBAAA,GAAoB;AAG1B,IAAM,iBAAA,GAAoB","file":"view-protocol.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// The view host API (tier 2 view extensions): the messages between a view, a\n// web component an extension's installed package supplies, and the app that\n// hosts it in a sandboxed floating window (patterkit design/view-extensions.md).\n//\n// Both ends import this module: the app through `hostView`, a view through\n// `@wildwinter/app-shell/view-client`. It is types and constants only, so a\n// view's bundle takes nothing else from the shell.\n//\n// The transport is a MessagePort straight from the view to the editor's\n// renderer, which holds what the writer sees in both apps. Nothing is\n// answered before the view's hello names the API it was built for; a host\n// that can't serve that API refuses it with a sentence and closes the port.\n// ---------------------------------------------------------------------------\n\n/** The API this shell's hosts and clients speak. A host serves exactly this version. */\nexport const VIEW_API = 1;\n\n/** A host: the app a view runs in. */\nexport type ViewHostName = \"patter\" | \"storylets\";\n\n/** A JSON value, as extension data and host fields are. */\nexport type ViewJson = string | number | boolean | null | ViewJson[] | { [key: string]: ViewJson };\n\n// --- What a host hands a view ---------------------------------------------\n\n/**\n * A node of the host's project, in one envelope for both hosts.\n *\n * `kind` is the manifest's node kind (`line`, `card`, `project`, ...). `host`\n * holds the host's own fields for that kind, documented per host in the\n * shell's README; `ext` holds extension data by extension id, the view's own\n * and those its manifest `reads`, nothing else.\n */\nexport interface ViewNode {\n  readonly id: string;\n  readonly kind: string;\n  /** The containing node's id; null for the project. */\n  readonly parent: string | null;\n  /** A short label for the node, in the source language, as the editor names it. */\n  readonly label: string;\n  readonly host: { readonly [field: string]: ViewJson };\n  readonly ext: { readonly [extension: string]: { readonly [field: string]: ViewJson } };\n  /** The node's children in order, when they were asked for. */\n  readonly children?: readonly ViewNode[];\n  /** Set when somebody else holds the view's own extension data on this node: the sentence saying who. A write\n   *  touching the node is refused `held`; a view can show the node read-only meanwhile. */\n  readonly held?: string;\n}\n\n/** The selection, innermost first (a line, then its snippet, block, and scene). Empty when nothing is selected. */\nexport interface ViewSelection {\n  readonly path: readonly { readonly id: string; readonly kind: string }[];\n}\n\n/** A line's length: a recording's when there is one (`measured`), else the host's estimate from its text. */\nexport interface ViewMediaLength {\n  readonly seconds: number;\n  readonly measured: boolean;\n}\n\n/** The app's theme, for the view to draw in: its CSS custom properties and its colour scheme. */\nexport interface ViewTheme {\n  readonly scheme: \"light\" | \"dark\";\n  /** Custom property names, with their leading `--`, and their computed values. */\n  readonly tokens: { readonly [name: string]: string };\n}\n\n/** Whether the view may write, and why not when it may not, as a sentence for the view to show. */\nexport interface ViewWritable {\n  readonly readOnly: boolean;\n  readonly why?: string;\n}\n\n/**\n * One write to the view's own extension data: a field on a node, set to a value, or cleared when `value` is absent.\n *\n * `field` is a top-level field the manifest declares for that node's kind, never a path into one: changing one\n * entry of a map or record writes the whole field's new value. Read the node again just before writing, so the\n * write builds on any edit made in the editor meanwhile; requests are answered in order, so nothing lands between.\n *\n * One write is one undo step in one history: its edits are all on the project node, or none of them are (the\n * project's data and a scene's sit in different histories in Patterpad). `hostView` refuses a write that mixes them.\n */\nexport interface ViewEdit {\n  readonly node: string;\n  readonly field: string;\n  readonly value?: ViewJson;\n}\n\n/** Why a request was refused: a stable code for the view, and a sentence for the writer. */\nexport interface ViewRefusal {\n  readonly code:\n    | \"bad-request\"   // the request's shape is wrong\n    | \"unsupported\"   // the host has no such thing (media in Storyletter)\n    | \"gone\"          // a node the request names doesn't exist\n    | \"held\"          // somebody else holds the data the write would change\n    | \"read-only\"     // the project or the view is read-only\n    | \"failed\";       // the host tried and couldn't\n  readonly message: string;\n}\n\n// --- Requests --------------------------------------------------------------\n\n/** Each request a view can make: what it sends, and what a granted reply carries. */\nexport interface ViewRequests {\n  /** The project node: the host's project facts (Patter: cast, qualifiers, pad default; Storylets: boxes, tag groups). */\n  project: { args: Record<string, never>; value: ViewNode };\n  /** One node by id, and its children in order when `children` is true; null when there is no such node. */\n  node: { args: { id: string; children?: boolean }; value: ViewNode | null };\n  selection: { args: Record<string, never>; value: ViewSelection };\n  /** Lines' lengths by id. Refused `unsupported` by a host with no media. */\n  media: { args: { ids: string[] }; value: { [id: string]: ViewMediaLength } };\n  /** Writes to the view's own extension, applied as one undo step with the label, or refused whole. */\n  write: { args: { label: string; edits: ViewEdit[] }; value: { written: number } };\n  /** Reveal and select a node in the editor. */\n  select: { args: { id: string }; value: boolean };\n}\n\nexport type ViewOp = keyof ViewRequests;\n\n// --- Messages ----------------------------------------------------------------\n\n/** A view's first message. */\nexport interface ViewHello { readonly t: \"hello\"; readonly api: number }\n\nexport interface ViewRequest<K extends ViewOp = ViewOp> {\n  readonly t: \"request\";\n  readonly id: number;\n  readonly op: K;\n  readonly args: ViewRequests[K][\"args\"];\n}\n\n/** A key combination the view didn't handle, in the shell's portable spelling (\"Mod+Z\", \"Mod+Shift+Z\"), for the host to run. */\nexport interface ViewKey { readonly t: \"key\"; readonly combo: string }\n\nexport type ViewToHost = ViewHello | ViewRequest | ViewKey;\n\n/** The host's answer to a hello it can serve. */\nexport interface ViewWelcome {\n  readonly t: \"welcome\";\n  readonly api: number;\n  readonly host: ViewHostName;\n  /** The view's extension: its id, the installed version, and the version the project pins, if any. */\n  readonly extension: { readonly id: string; readonly version: string; readonly pinned?: string };\n  /** The view's own id within its manifest. */\n  readonly view: string;\n  /** The extension's project settings, by name. */\n  readonly settings: { readonly [name: string]: string };\n  readonly theme: ViewTheme;\n  readonly writable: ViewWritable;\n}\n\n/** The host's answer to a hello it can't serve, before it closes the port. */\nexport interface ViewRefused { readonly t: \"refused\"; readonly message: string }\n\nexport type ViewReply =\n  | { readonly t: \"reply\"; readonly id: number; readonly ok: true; readonly value: unknown }\n  | { readonly t: \"reply\"; readonly id: number; readonly ok: false; readonly refusal: ViewRefusal };\n\n/** What the host tells a view unasked. */\nexport interface ViewEvents {\n  /** The project changed: these nodes, or anything (\"all\"). Debounced; read again what you show. */\n  changed: { nodes: readonly string[] | \"all\" };\n  selection: ViewSelection;\n  theme: ViewTheme;\n  writable: ViewWritable;\n  /** The window is closing; the port goes next. */\n  closing: Record<string, never>;\n}\n\nexport type ViewEventName = keyof ViewEvents;\n\nexport interface ViewEvent<K extends ViewEventName = ViewEventName> {\n  readonly t: \"event\";\n  readonly name: K;\n  readonly value: ViewEvents[K];\n}\n\nexport type HostToView = ViewWelcome | ViewRefused | ViewReply | ViewEvent;\n\n// --- The port's arrival --------------------------------------------------------\n\n/** The IPC channel main sends each end's port on. */\nexport const VIEW_PORT_CHANNEL = \"wildwinter-view:port\";\n\n/** The window message a preload posts a port with, so page code (which can't see ipcRenderer) can take it. */\nexport const VIEW_PORT_MESSAGE = \"wildwinter-view:port\";\n\n/** What main tells the editor about a view whose port it is handing over. */\nexport interface ViewPortMeta {\n  /** The view window's id, unique while it's open. */\n  readonly window: number;\n  readonly extension: string;\n  readonly view: string;\n  readonly version: string;\n  readonly pinned?: string;\n  /** Set, with no port, when the view window has closed: the editor drops its handle for `window`. */\n  readonly closed?: true;\n}\n\n// --- The host's side: what an app implements, and what hostView gives back ----\n\n/**\n * What an app supplies `hostView` for one open view: its own model, as the\n * writer sees it (unsaved edits included). `hostView` answers the protocol\n * from it, checks every request's shape, keeps `ext` to the view's own\n * extension and its manifest's `reads`, and refuses writes when not writable.\n * Any method may return a promise.\n */\nexport interface ViewAdapter {\n  readonly host: ViewHostName;\n  /** The project node. */\n  project(): ViewNode | Promise<ViewNode>;\n  node(id: string, children: boolean): ViewNode | null | Promise<ViewNode | null>;\n  selection(): ViewSelection | Promise<ViewSelection>;\n  /** Absent in a host with no media; `hostView` then refuses `media` as unsupported. */\n  media?(ids: readonly string[]): { [id: string]: ViewMediaLength } | Promise<{ [id: string]: ViewMediaLength }>;\n  /** Apply the edits to `extension`'s data as one undo step with the label, or refuse them all. */\n  write(extension: string, label: string, edits: readonly ViewEdit[]): void | ViewRefusal | Promise<void | ViewRefusal>;\n  select(id: string): boolean | Promise<boolean>;\n  writable(extension: string): ViewWritable;\n  /** The extension's project settings, by name. */\n  settings(extension: string): { [name: string]: string };\n  /** Run a key combination the view passed on (undo, redo, the app's shortcuts). */\n  key?(combo: string): void;\n}\n\n/** What `hostView` returns, and `hostViews` for every open view: the app calls these as its model, selection,\n *  theme, or locks change. */\nexport interface ViewHandle {\n  changed(nodes: readonly string[] | \"all\"): void;\n  selection(): void;\n  theme(): void;\n  writable(): void;\n  close(): void;\n}\n"]}

package/dist/view-protocol.d.cts

@@ -0,0 +1,257 @@
+/** The API this shell's hosts and clients speak. A host serves exactly this version. */
+declare const VIEW_API = 1;
+/** A host: the app a view runs in. */
+type ViewHostName = "patter" | "storylets";
+/** A JSON value, as extension data and host fields are. */
+type ViewJson = string | number | boolean | null | ViewJson[] | {
+    [key: string]: ViewJson;
+};
+/**
+ * A node of the host's project, in one envelope for both hosts.
+ *
+ * `kind` is the manifest's node kind (`line`, `card`, `project`, ...). `host`
+ * holds the host's own fields for that kind, documented per host in the
+ * shell's README; `ext` holds extension data by extension id, the view's own
+ * and those its manifest `reads`, nothing else.
+ */
+interface ViewNode {
+    readonly id: string;
+    readonly kind: string;
+    /** The containing node's id; null for the project. */
+    readonly parent: string | null;
+    /** A short label for the node, in the source language, as the editor names it. */
+    readonly label: string;
+    readonly host: {
+        readonly [field: string]: ViewJson;
+    };
+    readonly ext: {
+        readonly [extension: string]: {
+            readonly [field: string]: ViewJson;
+        };
+    };
+    /** The node's children in order, when they were asked for. */
+    readonly children?: readonly ViewNode[];
+    /** Set when somebody else holds the view's own extension data on this node: the sentence saying who. A write
+     *  touching the node is refused `held`; a view can show the node read-only meanwhile. */
+    readonly held?: string;
+}
+/** The selection, innermost first (a line, then its snippet, block, and scene). Empty when nothing is selected. */
+interface ViewSelection {
+    readonly path: readonly {
+        readonly id: string;
+        readonly kind: string;
+    }[];
+}
+/** A line's length: a recording's when there is one (`measured`), else the host's estimate from its text. */
+interface ViewMediaLength {
+    readonly seconds: number;
+    readonly measured: boolean;
+}
+/** The app's theme, for the view to draw in: its CSS custom properties and its colour scheme. */
+interface ViewTheme {
+    readonly scheme: "light" | "dark";
+    /** Custom property names, with their leading `--`, and their computed values. */
+    readonly tokens: {
+        readonly [name: string]: string;
+    };
+}
+/** Whether the view may write, and why not when it may not, as a sentence for the view to show. */
+interface ViewWritable {
+    readonly readOnly: boolean;
+    readonly why?: string;
+}
+/**
+ * One write to the view's own extension data: a field on a node, set to a value, or cleared when `value` is absent.
+ *
+ * `field` is a top-level field the manifest declares for that node's kind, never a path into one: changing one
+ * entry of a map or record writes the whole field's new value. Read the node again just before writing, so the
+ * write builds on any edit made in the editor meanwhile; requests are answered in order, so nothing lands between.
+ *
+ * One write is one undo step in one history: its edits are all on the project node, or none of them are (the
+ * project's data and a scene's sit in different histories in Patterpad). `hostView` refuses a write that mixes them.
+ */
+interface ViewEdit {
+    readonly node: string;
+    readonly field: string;
+    readonly value?: ViewJson;
+}
+/** Why a request was refused: a stable code for the view, and a sentence for the writer. */
+interface ViewRefusal {
+    readonly code: "bad-request" | "unsupported" | "gone" | "held" | "read-only" | "failed";
+    readonly message: string;
+}
+/** Each request a view can make: what it sends, and what a granted reply carries. */
+interface ViewRequests {
+    /** The project node: the host's project facts (Patter: cast, qualifiers, pad default; Storylets: boxes, tag groups). */
+    project: {
+        args: Record<string, never>;
+        value: ViewNode;
+    };
+    /** One node by id, and its children in order when `children` is true; null when there is no such node. */
+    node: {
+        args: {
+            id: string;
+            children?: boolean;
+        };
+        value: ViewNode | null;
+    };
+    selection: {
+        args: Record<string, never>;
+        value: ViewSelection;
+    };
+    /** Lines' lengths by id. Refused `unsupported` by a host with no media. */
+    media: {
+        args: {
+            ids: string[];
+        };
+        value: {
+            [id: string]: ViewMediaLength;
+        };
+    };
+    /** Writes to the view's own extension, applied as one undo step with the label, or refused whole. */
+    write: {
+        args: {
+            label: string;
+            edits: ViewEdit[];
+        };
+        value: {
+            written: number;
+        };
+    };
+    /** Reveal and select a node in the editor. */
+    select: {
+        args: {
+            id: string;
+        };
+        value: boolean;
+    };
+}
+type ViewOp = keyof ViewRequests;
+/** A view's first message. */
+interface ViewHello {
+    readonly t: "hello";
+    readonly api: number;
+}
+interface ViewRequest<K extends ViewOp = ViewOp> {
+    readonly t: "request";
+    readonly id: number;
+    readonly op: K;
+    readonly args: ViewRequests[K]["args"];
+}
+/** A key combination the view didn't handle, in the shell's portable spelling ("Mod+Z", "Mod+Shift+Z"), for the host to run. */
+interface ViewKey {
+    readonly t: "key";
+    readonly combo: string;
+}
+type ViewToHost = ViewHello | ViewRequest | ViewKey;
+/** The host's answer to a hello it can serve. */
+interface ViewWelcome {
+    readonly t: "welcome";
+    readonly api: number;
+    readonly host: ViewHostName;
+    /** The view's extension: its id, the installed version, and the version the project pins, if any. */
+    readonly extension: {
+        readonly id: string;
+        readonly version: string;
+        readonly pinned?: string;
+    };
+    /** The view's own id within its manifest. */
+    readonly view: string;
+    /** The extension's project settings, by name. */
+    readonly settings: {
+        readonly [name: string]: string;
+    };
+    readonly theme: ViewTheme;
+    readonly writable: ViewWritable;
+}
+/** The host's answer to a hello it can't serve, before it closes the port. */
+interface ViewRefused {
+    readonly t: "refused";
+    readonly message: string;
+}
+type ViewReply = {
+    readonly t: "reply";
+    readonly id: number;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly t: "reply";
+    readonly id: number;
+    readonly ok: false;
+    readonly refusal: ViewRefusal;
+};
+/** What the host tells a view unasked. */
+interface ViewEvents {
+    /** The project changed: these nodes, or anything ("all"). Debounced; read again what you show. */
+    changed: {
+        nodes: readonly string[] | "all";
+    };
+    selection: ViewSelection;
+    theme: ViewTheme;
+    writable: ViewWritable;
+    /** The window is closing; the port goes next. */
+    closing: Record<string, never>;
+}
+type ViewEventName = keyof ViewEvents;
+interface ViewEvent<K extends ViewEventName = ViewEventName> {
+    readonly t: "event";
+    readonly name: K;
+    readonly value: ViewEvents[K];
+}
+type HostToView = ViewWelcome | ViewRefused | ViewReply | ViewEvent;
+/** The IPC channel main sends each end's port on. */
+declare const VIEW_PORT_CHANNEL = "wildwinter-view:port";
+/** The window message a preload posts a port with, so page code (which can't see ipcRenderer) can take it. */
+declare const VIEW_PORT_MESSAGE = "wildwinter-view:port";
+/** What main tells the editor about a view whose port it is handing over. */
+interface ViewPortMeta {
+    /** The view window's id, unique while it's open. */
+    readonly window: number;
+    readonly extension: string;
+    readonly view: string;
+    readonly version: string;
+    readonly pinned?: string;
+    /** Set, with no port, when the view window has closed: the editor drops its handle for `window`. */
+    readonly closed?: true;
+}
+/**
+ * What an app supplies `hostView` for one open view: its own model, as the
+ * writer sees it (unsaved edits included). `hostView` answers the protocol
+ * from it, checks every request's shape, keeps `ext` to the view's own
+ * extension and its manifest's `reads`, and refuses writes when not writable.
+ * Any method may return a promise.
+ */
+interface ViewAdapter {
+    readonly host: ViewHostName;
+    /** The project node. */
+    project(): ViewNode | Promise<ViewNode>;
+    node(id: string, children: boolean): ViewNode | null | Promise<ViewNode | null>;
+    selection(): ViewSelection | Promise<ViewSelection>;
+    /** Absent in a host with no media; `hostView` then refuses `media` as unsupported. */
+    media?(ids: readonly string[]): {
+        [id: string]: ViewMediaLength;
+    } | Promise<{
+        [id: string]: ViewMediaLength;
+    }>;
+    /** Apply the edits to `extension`'s data as one undo step with the label, or refuse them all. */
+    write(extension: string, label: string, edits: readonly ViewEdit[]): void | ViewRefusal | Promise<void | ViewRefusal>;
+    select(id: string): boolean | Promise<boolean>;
+    writable(extension: string): ViewWritable;
+    /** The extension's project settings, by name. */
+    settings(extension: string): {
+        [name: string]: string;
+    };
+    /** Run a key combination the view passed on (undo, redo, the app's shortcuts). */
+    key?(combo: string): void;
+}
+/** What `hostView` returns, and `hostViews` for every open view: the app calls these as its model, selection,
+ *  theme, or locks change. */
+interface ViewHandle {
+    changed(nodes: readonly string[] | "all"): void;
+    selection(): void;
+    theme(): void;
+    writable(): void;
+    close(): void;
+}
+
+export { type HostToView, VIEW_API, VIEW_PORT_CHANNEL, VIEW_PORT_MESSAGE, type ViewAdapter, type ViewEdit, type ViewEvent, type ViewEventName, type ViewEvents, type ViewHandle, type ViewHello, type ViewHostName, type ViewJson, type ViewKey, type ViewMediaLength, type ViewNode, type ViewOp, type ViewPortMeta, type ViewRefusal, type ViewRefused, type ViewReply, type ViewRequest, type ViewRequests, type ViewSelection, type ViewTheme, type ViewToHost, type ViewWelcome, type ViewWritable };

package/dist/view-protocol.d.ts

@@ -0,0 +1,257 @@
+/** The API this shell's hosts and clients speak. A host serves exactly this version. */
+declare const VIEW_API = 1;
+/** A host: the app a view runs in. */
+type ViewHostName = "patter" | "storylets";
+/** A JSON value, as extension data and host fields are. */
+type ViewJson = string | number | boolean | null | ViewJson[] | {
+    [key: string]: ViewJson;
+};
+/**
+ * A node of the host's project, in one envelope for both hosts.
+ *
+ * `kind` is the manifest's node kind (`line`, `card`, `project`, ...). `host`
+ * holds the host's own fields for that kind, documented per host in the
+ * shell's README; `ext` holds extension data by extension id, the view's own
+ * and those its manifest `reads`, nothing else.
+ */
+interface ViewNode {
+    readonly id: string;
+    readonly kind: string;
+    /** The containing node's id; null for the project. */
+    readonly parent: string | null;
+    /** A short label for the node, in the source language, as the editor names it. */
+    readonly label: string;
+    readonly host: {
+        readonly [field: string]: ViewJson;
+    };
+    readonly ext: {
+        readonly [extension: string]: {
+            readonly [field: string]: ViewJson;
+        };
+    };
+    /** The node's children in order, when they were asked for. */
+    readonly children?: readonly ViewNode[];
+    /** Set when somebody else holds the view's own extension data on this node: the sentence saying who. A write
+     *  touching the node is refused `held`; a view can show the node read-only meanwhile. */
+    readonly held?: string;
+}
+/** The selection, innermost first (a line, then its snippet, block, and scene). Empty when nothing is selected. */
+interface ViewSelection {
+    readonly path: readonly {
+        readonly id: string;
+        readonly kind: string;
+    }[];
+}
+/** A line's length: a recording's when there is one (`measured`), else the host's estimate from its text. */
+interface ViewMediaLength {
+    readonly seconds: number;
+    readonly measured: boolean;
+}
+/** The app's theme, for the view to draw in: its CSS custom properties and its colour scheme. */
+interface ViewTheme {
+    readonly scheme: "light" | "dark";
+    /** Custom property names, with their leading `--`, and their computed values. */
+    readonly tokens: {
+        readonly [name: string]: string;
+    };
+}
+/** Whether the view may write, and why not when it may not, as a sentence for the view to show. */
+interface ViewWritable {
+    readonly readOnly: boolean;
+    readonly why?: string;
+}
+/**
+ * One write to the view's own extension data: a field on a node, set to a value, or cleared when `value` is absent.
+ *
+ * `field` is a top-level field the manifest declares for that node's kind, never a path into one: changing one
+ * entry of a map or record writes the whole field's new value. Read the node again just before writing, so the
+ * write builds on any edit made in the editor meanwhile; requests are answered in order, so nothing lands between.
+ *
+ * One write is one undo step in one history: its edits are all on the project node, or none of them are (the
+ * project's data and a scene's sit in different histories in Patterpad). `hostView` refuses a write that mixes them.
+ */
+interface ViewEdit {
+    readonly node: string;
+    readonly field: string;
+    readonly value?: ViewJson;
+}
+/** Why a request was refused: a stable code for the view, and a sentence for the writer. */
+interface ViewRefusal {
+    readonly code: "bad-request" | "unsupported" | "gone" | "held" | "read-only" | "failed";
+    readonly message: string;
+}
+/** Each request a view can make: what it sends, and what a granted reply carries. */
+interface ViewRequests {
+    /** The project node: the host's project facts (Patter: cast, qualifiers, pad default; Storylets: boxes, tag groups). */
+    project: {
+        args: Record<string, never>;
+        value: ViewNode;
+    };
+    /** One node by id, and its children in order when `children` is true; null when there is no such node. */
+    node: {
+        args: {
+            id: string;
+            children?: boolean;
+        };
+        value: ViewNode | null;
+    };
+    selection: {
+        args: Record<string, never>;
+        value: ViewSelection;
+    };
+    /** Lines' lengths by id. Refused `unsupported` by a host with no media. */
+    media: {
+        args: {
+            ids: string[];
+        };
+        value: {
+            [id: string]: ViewMediaLength;
+        };
+    };
+    /** Writes to the view's own extension, applied as one undo step with the label, or refused whole. */
+    write: {
+        args: {
+            label: string;
+            edits: ViewEdit[];
+        };
+        value: {
+            written: number;
+        };
+    };
+    /** Reveal and select a node in the editor. */
+    select: {
+        args: {
+            id: string;
+        };
+        value: boolean;
+    };
+}
+type ViewOp = keyof ViewRequests;
+/** A view's first message. */
+interface ViewHello {
+    readonly t: "hello";
+    readonly api: number;
+}
+interface ViewRequest<K extends ViewOp = ViewOp> {
+    readonly t: "request";
+    readonly id: number;
+    readonly op: K;
+    readonly args: ViewRequests[K]["args"];
+}
+/** A key combination the view didn't handle, in the shell's portable spelling ("Mod+Z", "Mod+Shift+Z"), for the host to run. */
+interface ViewKey {
+    readonly t: "key";
+    readonly combo: string;
+}
+type ViewToHost = ViewHello | ViewRequest | ViewKey;
+/** The host's answer to a hello it can serve. */
+interface ViewWelcome {
+    readonly t: "welcome";
+    readonly api: number;
+    readonly host: ViewHostName;
+    /** The view's extension: its id, the installed version, and the version the project pins, if any. */
+    readonly extension: {
+        readonly id: string;
+        readonly version: string;
+        readonly pinned?: string;
+    };
+    /** The view's own id within its manifest. */
+    readonly view: string;
+    /** The extension's project settings, by name. */
+    readonly settings: {
+        readonly [name: string]: string;
+    };
+    readonly theme: ViewTheme;
+    readonly writable: ViewWritable;
+}
+/** The host's answer to a hello it can't serve, before it closes the port. */
+interface ViewRefused {
+    readonly t: "refused";
+    readonly message: string;
+}
+type ViewReply = {
+    readonly t: "reply";
+    readonly id: number;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly t: "reply";
+    readonly id: number;
+    readonly ok: false;
+    readonly refusal: ViewRefusal;
+};
+/** What the host tells a view unasked. */
+interface ViewEvents {
+    /** The project changed: these nodes, or anything ("all"). Debounced; read again what you show. */
+    changed: {
+        nodes: readonly string[] | "all";
+    };
+    selection: ViewSelection;
+    theme: ViewTheme;
+    writable: ViewWritable;
+    /** The window is closing; the port goes next. */
+    closing: Record<string, never>;
+}
+type ViewEventName = keyof ViewEvents;
+interface ViewEvent<K extends ViewEventName = ViewEventName> {
+    readonly t: "event";
+    readonly name: K;
+    readonly value: ViewEvents[K];
+}
+type HostToView = ViewWelcome | ViewRefused | ViewReply | ViewEvent;
+/** The IPC channel main sends each end's port on. */
+declare const VIEW_PORT_CHANNEL = "wildwinter-view:port";
+/** The window message a preload posts a port with, so page code (which can't see ipcRenderer) can take it. */
+declare const VIEW_PORT_MESSAGE = "wildwinter-view:port";
+/** What main tells the editor about a view whose port it is handing over. */
+interface ViewPortMeta {
+    /** The view window's id, unique while it's open. */
+    readonly window: number;
+    readonly extension: string;
+    readonly view: string;
+    readonly version: string;
+    readonly pinned?: string;
+    /** Set, with no port, when the view window has closed: the editor drops its handle for `window`. */
+    readonly closed?: true;
+}
+/**
+ * What an app supplies `hostView` for one open view: its own model, as the
+ * writer sees it (unsaved edits included). `hostView` answers the protocol
+ * from it, checks every request's shape, keeps `ext` to the view's own
+ * extension and its manifest's `reads`, and refuses writes when not writable.
+ * Any method may return a promise.
+ */
+interface ViewAdapter {
+    readonly host: ViewHostName;
+    /** The project node. */
+    project(): ViewNode | Promise<ViewNode>;
+    node(id: string, children: boolean): ViewNode | null | Promise<ViewNode | null>;
+    selection(): ViewSelection | Promise<ViewSelection>;
+    /** Absent in a host with no media; `hostView` then refuses `media` as unsupported. */
+    media?(ids: readonly string[]): {
+        [id: string]: ViewMediaLength;
+    } | Promise<{
+        [id: string]: ViewMediaLength;
+    }>;
+    /** Apply the edits to `extension`'s data as one undo step with the label, or refuse them all. */
+    write(extension: string, label: string, edits: readonly ViewEdit[]): void | ViewRefusal | Promise<void | ViewRefusal>;
+    select(id: string): boolean | Promise<boolean>;
+    writable(extension: string): ViewWritable;
+    /** The extension's project settings, by name. */
+    settings(extension: string): {
+        [name: string]: string;
+    };
+    /** Run a key combination the view passed on (undo, redo, the app's shortcuts). */
+    key?(combo: string): void;
+}
+/** What `hostView` returns, and `hostViews` for every open view: the app calls these as its model, selection,
+ *  theme, or locks change. */
+interface ViewHandle {
+    changed(nodes: readonly string[] | "all"): void;
+    selection(): void;
+    theme(): void;
+    writable(): void;
+    close(): void;
+}
+
+export { type HostToView, VIEW_API, VIEW_PORT_CHANNEL, VIEW_PORT_MESSAGE, type ViewAdapter, type ViewEdit, type ViewEvent, type ViewEventName, type ViewEvents, type ViewHandle, type ViewHello, type ViewHostName, type ViewJson, type ViewKey, type ViewMediaLength, type ViewNode, type ViewOp, type ViewPortMeta, type ViewRefusal, type ViewRefused, type ViewReply, type ViewRequest, type ViewRequests, type ViewSelection, type ViewTheme, type ViewToHost, type ViewWelcome, type ViewWritable };

package/dist/view-protocol.js

@@ -0,0 +1,3 @@
+export { VIEW_API, VIEW_PORT_CHANNEL, VIEW_PORT_MESSAGE } from './chunk-ICYPXUNA.js';
+//# sourceMappingURL=view-protocol.js.map
+//# sourceMappingURL=view-protocol.js.map

package/dist/view-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"view-protocol.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildwinter/app-shell",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "The shared shell for the editor family (Patterpad, Storylet Studio): the app-agnostic design-token grammar, the per-entity colour hash, and the vanilla-TS DOM primitive. Two palettes, one grammar - each app supplies its own palette/fonts over these tokens.",
   "type": "module",
   "license": "MIT",
@@ -229,7 +229,28 @@
     "./link-status.css": {
       "import": "./dist/link-status.css",
       "require": "./dist/link-status.css"
-    }
+    },
+    "./view-protocol": {
+      "types": "./dist/view-protocol.d.ts",
+      "import": "./dist/view-protocol.js",
+      "require": "./dist/view-protocol.cjs"
+    },
+    "./view-client": {
+      "types": "./dist/view-client.d.ts",
+      "import": "./dist/view-client.js",
+      "require": "./dist/view-client.cjs"
+    },
+    "./view-host": {
+      "types": "./dist/view-host.d.ts",
+      "import": "./dist/view-host.js",
+      "require": "./dist/view-host.cjs"
+    },
+    "./view-host-web": {
+      "types": "./dist/view-host-web.d.ts",
+      "import": "./dist/view-host-web.js",
+      "require": "./dist/view-host-web.cjs"
+    },
+    "./view-preload.cjs": "./dist/view-preload.cjs"
   },
   "files": [
     "dist",
@@ -254,7 +275,7 @@
   },
   "peerDependencies": {
     "@wildwinter/simple-vc-lib": ">=0.5.0",
-    "@wildwinter/toolkit": ">=0.2.5 <1.0.0",
+    "@wildwinter/toolkit": ">=0.2.6 <1.0.0",
     "electron": ">=28",
     "electron-updater": ">=6",
     "ws": ">=8"
@@ -281,7 +302,7 @@
     "@wildwinter/expr": "^0.6.0",
     "@wildwinter/scoperegistry": "^0.9.0",
     "@wildwinter/simple-vc-lib": "^0.5.2",
-    "@wildwinter/toolkit": "^0.2.5",
+    "@wildwinter/toolkit": "^0.2.6",
     "electron": "42.6.0",
     "electron-updater": "^6.8.9",
     "jsdom": "^25.0.0",