@vestra-player/sdk 1.5.3 → 1.5.6

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.5.6
+
+**A reference for AI assistants.** Documentation and packaging only; no API change, `apiVersion` stays `vestra/1`. (1.5.5 was not published to npm; this release includes its changes.)
+
+- **`llms.txt` and `llms-full.txt`** ([llmstxt.org](https://llmstxt.org)) in the package, exported as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt` (in `node_modules/@vestra-player/sdk/`), and on the documentation site (`https://vestrasys.github.io/vestra-player-sdk/llms.txt`). For Vestra Player AI and other assistants that write plugins.
+  - `llms.txt` (about 10 KB): what a plugin is, the rules, the folder layout, a manifest with every field and the manifest limits, `activate`, every capability, a `TestHost` test, the command line, the common error codes, and the line numbers of each topic in the full file.
+  - `llms-full.txt` (about 300 KB): the guides (Getting started, the UI concept page, both how-tos), every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its description and its `@capability`, `@player`, `@param`, `@returns`, `@throws` and `@deprecated` tags, the internal types the API refers to, and each example's README, walkthrough and complete source (TypeScript, Slint, tests).
+  - Generated from the sources by `npm run docs:llms` (`scripts/llms.mjs`); CI fails when the committed files are stale.
+- **Getting started**: a "Rules for plugins" section (only the public SDK, `import type`, no other plugins, no system commands, macOS and Windows, your own id) and a manifest with every field.
+- `scripts/check-pack.mjs` allows the two files and checks that they name the package version; the install smoke test resolves both exports.
+
+## 1.5.5
+
+**Reserved `vestra.` ids** (player 0.4.1). Documentation only; no API change, `apiVersion` stays `vestra/1`.
+
+- Only the plugins built into the player are official plugins; the ids `vestra` and `vestra.*` (any case) are reserved for them. Every other plugin is a third-party plugin, including those hosted in the official plugin repository, and uses `<GitHub user or organization>.<plugin name>`.
+- `PluginError` lists the code `reserved`: `packages.validate`, `packages.validateArchive`, `PackageCandidate.trial` and `PackageCandidate.install` refuse a package with a reserved id. Development loads (`vestra-player --plugin DIR`) still accept one, with a warning, so built-in plugins can be developed; they are never installed.
+## 1.5.4
+
+**Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.
+
+- **A `MarkdownRef` at any depth.** A document from `plugin.ui.markdown` may now be a field at any depth of a property value, wherever the Slint type is `[MarkdownBlock]`: for example the `body` of each row of a chat's `[Message]` list. Before, it could only be the whole value of a `[MarkdownBlock]` property. `PropValue` is now `PropData | ImageRef`, where the new **`PropData`** is JSON whose values may also be `MarkdownRef`s, at any depth. A released document is refused with `invalid` wherever it is in the value. An `ImageRef` stays a whole value only: nested in an array or object it is `invalid` (a type error in TypeScript, and refused by the SDK and the player). Older players refuse a nested document like any value they cannot convert.
+- **Limits:** a document still holds at most 256 KB of text, 4000 blocks and 64 images; all of a value's text, its documents' text included, counts toward the value's 1 MiB; each document is one of its 4096 values.
+- **`MarkdownBlocks`** (new in `@vestra/markdown.slint`): the blocks of a document without scrolling, as tall as their content, for your own layout or a `ListView` row. `in [MarkdownBlock] blocks`, `in bool code-copy` (default `false`), callbacks `link-clicked(string)` and `copy-code(string)`. `MarkdownView` is now a `ScrollView` around it and gains the same `code-copy` and `copy-code`; it looks as before.
+- **Code copy, opt in.** With `code-copy: true`, code blocks get a 复制 button that reports `copy-code(code)` with the block's text; the plugin copies it (`plugin.clipboard.writeText`). Off by default: views that do not set it look and behave as before.
+- **Cheaper updates** (player): writing a value again with unchanged documents does not parse them again (a new reference for the same text included), and a value with documents is updated in place where its shape allows: changed rows, rows added or removed at the end, and only the changed blocks of a changed document. Streaming a reply into the last row of a 200-message list therefore keeps the list, its scroll position and the other rows. Nothing to change in plugins.
+- `TestHost` keeps nested documents in the view's properties as they were sent; `host.markdown(value)` reads one back from a field (`host.markdown(rows[0].body)`).
 ## 1.5.3
 
 **File resolvers: local files as generated streams** (player 0.4.1). Additive; `apiVersion` stays `vestra/1`. Plugins that register one set `"minPlayerVersion": "0.4.1"`: an older player refuses the declaration (`invalid`).

package/README.md

@@ -12,7 +12,8 @@
   <a href="https://vestrasys.github.io/vestra-player-sdk/">Documentation</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html">Getting started</a> ·
   <a href="https://github.com/vestrasys/vestra-player-sdk/tree/main/examples">Examples</a> ·
-  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a>
+  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
 ## Features
 
@@ -21,6 +22,7 @@
 - **Tests without the player**: `@vestra-player/sdk/testing` runs your plugin against an in-memory host with `node --test`.
 - **One command line tool**, `vestra-plugin`, to check, test, build and pack a `.vxp` package.
 - **The same API on macOS and Windows**; every plugin runs in its own Node.js 26 process that the player ships.
+- **A reference for AI assistants**: [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (short index) and [`llms-full.txt`](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt) (every declaration, the guides and the examples), also in the package as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt`.
 
 ## Install
 

package/dist/plugin/testing.d.ts

@@ -1128,9 +1128,16 @@ export declare class TestHost implements Transport {
      */
     readonly remoteImages: Map<string, string | null>;
     /**
-     * The Markdown document a property holds (its wire form read back), or
+     * The Markdown document a value holds (its wire form read back), or
      * `null` when the value is not one. `images` maps each remote address to
-     * the downloaded file.
+     * the downloaded file. Pass a whole property value or a field of one: a
+     * document nested in rows is read the same way.
+     *
+     * @example
+     * ```ts
+     * const rows = host.window("chat").props["messages"] as { body: Json }[];
+     * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+     * ```
      */
     markdown(value: Json | undefined): MarkdownWire | null;
     /**

package/dist/plugin/testing.js

@@ -1482,9 +1482,16 @@ export class TestHost {
      */
     remoteImages = new Map();
     /**
-     * The Markdown document a property holds (its wire form read back), or
+     * The Markdown document a value holds (its wire form read back), or
      * `null` when the value is not one. `images` maps each remote address to
-     * the downloaded file.
+     * the downloaded file. Pass a whole property value or a field of one: a
+     * document nested in rows is read the same way.
+     *
+     * @example
+     * ```ts
+     * const rows = host.window("chat").props["messages"] as { body: Json }[];
+     * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+     * ```
      */
     markdown(value) {
         const doc = value

package/dist/plugin/types.d.ts

@@ -75,6 +75,7 @@ export interface Disposable {
  * | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
  * | `cleanup` | {@link PackageTrial.stop} could not confirm cleanup; call it again. |
  * | `limit` | A player-wide limit was reached (for example the number of commands). |
+ * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.trial}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
  * | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
  * | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
  * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
@@ -562,18 +563,31 @@ export interface ImageRef {
     readonly __vestraImage: true;
 }
 /**
- * A Markdown document for `MarkdownView`, made by {@link Ui.markdown}.
+ * A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
+ * {@link Ui.markdown}.
  *
  * @remarks
- * Opaque, like {@link ImageRef}: pass it as the whole value of a
- * `[MarkdownBlock]` property (the `blocks` of `MarkdownView` from
- * `@vestra/markdown.slint`). It carries the text, the base address and the
- * local copies of its remote images; the player parses and draws it. It
- * belongs to the scope that created it: once that scope is disposed, writing
- * it fails with `invalid`.
- *
- * @player 0.2.0
- * @see {@link Ui.markdown}, {@link MarkdownOptions}
+ * Opaque, like {@link ImageRef}: pass it where the Slint type is
+ * `[MarkdownBlock]`: the whole value of such a property (the `blocks` of
+ * `MarkdownView` from `@vestra/markdown.slint`) or, from SDK 1.5.4, a
+ * `[MarkdownBlock]` field at any depth of a property value, such as the
+ * `body` of each row of a chat's message list. It carries the text, the
+ * base address and the local copies of its remote images; the player parses
+ * and draws it. Writing a document whose text did not change (a new
+ * reference for the same text included) costs the player no parsing, and a
+ * changed document updates only the blocks that changed. It belongs to the
+ * scope that created it: once that scope is disposed, writing it fails with
+ * `invalid`, wherever it is in the value.
+ *
+ * @example Chat messages, one document per row
+ * ```ts
+ * const chat = plugin.windows.create("ui/chat.slint");
+ * const body = await plugin.ui.markdown("**Hello**", { remoteImages: false });
+ * chat.set({ messages: [{ id: "m1", role: "assistant", body }] });
+ * ```
+ *
+ * @player 0.2.0; nested in a value: the player after 0.4.0
+ * @see {@link Ui.markdown}, {@link MarkdownOptions}, {@link PropValue}
  * @since 1.1.0
  * @category UI
  */
@@ -607,8 +621,9 @@ export interface MarkdownOptions {
     remoteImages?: boolean;
 }
 /**
- * The value of one Slint property: JSON, or an image or a Markdown document
- * as the whole value of a property.
+ * The value of one Slint property: JSON with Markdown documents at any
+ * depth ({@link PropData}), or an image as the whole value of an `image`
+ * property.
  *
  * @remarks
  * JSON becomes Slint values as you would expect: booleans for `bool`,
@@ -618,14 +633,37 @@ export interface MarkdownOptions {
  * is refused (Slint treats `_` and `-` as the same, so use camelCase or
  * kebab-case).
  *
- * Limits per value: nesting depth 8, 4096 values in total, 1024 rows per
- * array, 64 KiB per string and 1 MiB of text in total. A value over a limit
- * is a failed write (see {@link View}).
+ * A {@link MarkdownRef} goes where the Slint type is `[MarkdownBlock]`: the
+ * whole value, or a field at any depth (SDK 1.5.4; older players refuse a
+ * nested one). An {@link ImageRef} only as the whole value: nested in an
+ * array or object it is `invalid`.
+ *
+ * Limits per value: nesting depth 8, 4096 values in total (a document is
+ * one), 1024 rows per array, 64 KiB per string and 1 MiB of text in total,
+ * the text of its Markdown documents included (256 KB per document). A
+ * value over a limit is a failed write (see {@link View}).
  *
  * @since 1.0.0
  * @category UI
  */
-export type PropValue = Json | ImageRef | MarkdownRef;
+export type PropValue = PropData | ImageRef;
+/**
+ * JSON whose values may also be Markdown documents, at any depth: the part
+ * of {@link PropValue} that nests.
+ *
+ * @example A message list whose rows carry a document
+ * ```ts
+ * const messages: PropData = [
+ *   { id: "m1", role: "user", body: await plugin.ui.markdown("Hi") },
+ * ];
+ * ```
+ *
+ * @since 1.5.4
+ * @category UI
+ */
+export type PropData = null | boolean | number | string | MarkdownRef | PropData[] | {
+    [key: string]: PropData;
+};
 /**
  * Properties to write to a view, by name.
  *
@@ -4046,13 +4084,18 @@ export interface PackageCandidate {
     readonly manifest: PackageManifest;
     /** The checks the player ran. */
     readonly checks: string[];
-    /** Load it temporarily alongside the installed plugins. */
+    /**
+     * Load it temporarily alongside the installed plugins. A reserved id
+     * (`vestra.*`) fails with `reserved`.
+     */
     trial(): Promise<PackageTrial>;
     /**
      * Install it. The same source upgrades the installed plugin (its data
      * stays); another source fails with `conflict` unless `replace` is set;
      * a built-in id fails with `unsupported` (built-ins update with the
-     * player).
+     * player). A reserved id (`vestra` or `vestra.*`, which every built-in
+     * uses) fails with `reserved` (player 0.4.1; already when validated), as
+     * only the player installs built-in plugins.
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
@@ -4160,12 +4203,17 @@ export interface PluginWarning {
  * ```
  */
 export interface Packages {
-    /** Validate a package directory (`plugins.manage`). */
+    /**
+     * Validate a package directory (`plugins.manage`). A package whose id is
+     * reserved for the built-in plugins (`vestra` or `vestra.*`) fails with
+     * `reserved` (player 0.4.1).
+     */
     validate(directory: string): Promise<PackageCandidate>;
     /**
      * Validate a `.vxp` package file (`plugins.manage`, player 0.2.0): the
      * same checks as {@link Packages.validate} after unpacking. Check the
-     * file's sha256 yourself before calling when you know it.
+     * file's sha256 yourself before calling when you know it. A reserved id
+     * fails with `reserved`, as in {@link Packages.validate}.
      */
     validateArchive(file: string): Promise<PackageCandidate>;
     /** Restore a plugin's previous version (`plugins.manage`). */

package/dist/plugin/ui.js

@@ -31,18 +31,33 @@ export class ImageHandle {
         return { $vestraImage: this.path, ref: this.#ref };
     }
 }
-/** A property value as sent: images and documents in wire form; released ones refused. */
-function wireValue(value) {
+/**
+ * A property value as sent: images and documents in wire form, documents at
+ * any depth (released ones refused wherever they are); an image only as the
+ * whole value, like the player.
+ */
+function wireValue(value, nested = false) {
     if (value instanceof MarkdownHandle) {
         if (value.released)
             throw failure("invalid", "Markdown document was released with the scope that created it");
         return value.toJSON();
     }
-    if (!(value instanceof ImageHandle))
-        return value;
-    if (value.released)
-        throw failure("invalid", `image ${value.path} was released with the scope that created it`);
-    return value.toJSON();
+    if (value instanceof ImageHandle) {
+        if (nested)
+            throw failure("invalid", `image ${value.path}: an image reference must be the whole value of an image property`);
+        if (value.released)
+            throw failure("invalid", `image ${value.path} was released with the scope that created it`);
+        return value.toJSON();
+    }
+    if (Array.isArray(value))
+        return value.map((item) => wireValue(item, true));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = wireValue(item, true);
+        return out;
+    }
+    return value;
 }
 export const ui = (scope) => ({
     image(path) {