flare-plugin-sdk 0.1.0-beta.5 → 0.1.0-beta.8

package/skill/flare-plugin/references/manifest.md

@@ -6,10 +6,52 @@ Defaults below apply when a field is omitted; use omission for optional fields
 rather than sending null for non-nullable values. Start from the complete
 [template manifest](../assets/github-template/manifest.json).
 
+## JSON Schema and editor support
+
+The self-contained [manifest.schema.json](../manifest.schema.json) uses JSON Schema
+draft-07. Editors such as VS Code use it for field completion, descriptions, enum
+choices, required properties, ranges and static login/capability combinations.
+`npx flare-plugin-sdk@next init my-plugin` adds a `$schema` URL pinned to that SDK
+version. The source templates use the npm `next` channel.
+
+For an existing project, add this editor hint at the manifest root:
+
+```json
+{
+  "$schema": "https://unpkg.com/flare-plugin-sdk@next/skill/flare-plugin/manifest.schema.json"
+}
+```
+
+Keep the other manifest fields. For reproducible editor behavior, replace `next`
+with your chosen SDK version. For offline authoring, install the SDK as a development
+dependency and use `./node_modules/flare-plugin-sdk/skill/flare-plugin/manifest.schema.json`
+as the `$schema` value; all schema references are local to that file.
+
+Flare accepts `$schema` as optional editor metadata and never fetches or executes
+it. Older Flare builds that reject it can still use editor assistance: remove
+`$schema` from the manifest and associate the schema in VS Code workspace settings
+(`.vscode/settings.json`):
+
+```json
+{
+  "json.schemas": [{
+    "fileMatch": ["/manifest.json"],
+    "url": "https://unpkg.com/flare-plugin-sdk@next/skill/flare-plugin/manifest.schema.json"
+  }]
+}
+```
+
+Schema validation does not fill defaults or replace Host validation. Flare also
+checks unique IDs/interactions, canonical/approved origins, captured Deep Link
+values, referenced timelines, localized catalog keys, relational compose limits,
+actual JavaScript registration and runtime behavior. Some text limits use UTF-16
+length in the Host rather than JSON Schema's Unicode code point count.
+
 ## Root object
 
 | Field | Required / default | Contract |
 | --- | --- | --- |
+| `$schema` | Omitted | Editor schema URL/path only; never loaded by Flare |
 | `schemaVersion` | `1` | Manifest schema, currently exactly 1 |
 | `apiVersion` | Required | Runtime ABI, currently exactly 1 |
 | `id` | Required | Stable reverse-domain plugin ID; `[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)+` |

package/skill/flare-plugin/references/publishing.md

@@ -31,6 +31,9 @@ copy that example's contents into a repository you own first.
    by `npx flare-plugin-sdk@next init my-plugin` stable.
    Keep real tokens, Cookies, passwords, and private fixtures out of Git history.
 2. Put the required files at root and check that a clean checkout contains them.
+   For the TS starter, run `npm run build` and commit `src/`, the build files,
+   `package-lock.json`, and the newly built root `plugin.js`. Keep `plugin.js`
+   tracked; the generated `.gitignore` excludes dependencies and local artifacts.
    Include README instructions for supported website/instances, token acquisition
    if relevant, features, permissions, and tests actually performed.
 3. Set a stable SemVer manifest version, for example `0.1.0`. Publish a tag
@@ -101,8 +104,19 @@ plugin authors do not control it.
 
 ## Optional local installation
 
-Use `.fpp` as an alternative for offline transfer or local testing. In your plugin
-project, create a new, empty `dist` directory. Copy only `manifest.json`, `plugin.js`,
+Use `.fpp` as an alternative for offline transfer or local testing. From the
+generated TS project, run:
+
+```sh
+npm run package
+```
+
+It checks types, rebuilds the root script, stages only runtime files in a fresh
+temporary directory and invokes the SDK packer. The result is `plugin.fpp` at
+project root; temporary staging is cleaned up. GitHub remains the recommended
+distribution path and this file has no GitHub update tracking.
+
+For other project layouts, create a new, empty `dist` directory. Copy only `manifest.json`, `plugin.js`,
 one supported `assets/icon.<extension>`, and optional `locales/*.json` into it,
 preserving those paths. From the project root:
 
@@ -114,7 +128,7 @@ The complete skill also includes the standard-library-only packer for use withou
 npm. For example, from this skill directory:
 
 ```sh
-node pack.mjs assets/github-template /tmp/example-feed-0.1.0.fpp
+node pack.mjs /path/to/runtime-directory /tmp/example-feed-0.1.0.fpp
 ```
 
 The packer ignores only a root README.md; unlike GitHub import it rejects other

package/skill/flare-plugin/references/testing.md

@@ -7,15 +7,19 @@ No demonstration backend is required for authoring this SDK.
 
 ## Checks in a generated repository
 
-From the generated repository root, using Node:
+The generated TS project includes a prebuilt root `plugin.js`. From its root:
 
 ```sh
+npm install
+npm run check
+npm run build
 node --check plugin.js
 node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
 ```
 
-These are syntax checks only: Node accepts APIs that the plugin Host does not
-provide, and parsing JSON does not validate the manifest. Also inspect:
+The SDK types help check source code; building emits one self-contained ES2020
+IIFE. CI checks that it matches the committed prebuilt script. Type/syntax checks
+do not replace Host validation, and parsing JSON does not validate the manifest. Also inspect:
 
 - Required root files and a valid supported icon; stable IDs and version/tag consistency.
 - Every declared known operation has its required registration and full method
@@ -27,9 +31,8 @@ provide, and parsing JSON does not validate the manifest. Also inspect:
 - Auth/cursor/action data is not accidentally inserted into public content or
   media URLs. No real secrets enter checked-in fixtures.
 
-Use the shipped `.d.ts` as editor/reference input, outside the release package.
-For a TypeScript authoring project, reference that file and configure the actual
-bundler to emit one classic script. Keep manifest/Host validation even when the
+The generated tsconfig loads the SDK's ambient types with strict checking and no
+browser/Node globals. Keep manifest/Host validation even when the
 type checker passes: TypeScript optional service properties do not express all
 capability requirements, and optionality does not make every null value valid.
 
@@ -39,11 +42,15 @@ In Settings > Plugins, open the overflow menu and choose **Plugin development**.
 Choose the directory containing `manifest.json`, `plugin.js`, and the plugin assets.
 Click **Start development** and review access to your existing accounts. Both Compose Desktop and native macOS support this flow.
 
-Edit `plugin.js`, `manifest.json`, `assets/icon.<extension>`, or `locales/*.json`. Flare
-automatically validates the files; click **Reload plugin** to apply the validated
+For the TS starter, run `npm run dev` and edit `src/plugin.ts` or its local modules.
+The watcher rebuilds the root `plugin.js`; syntax/build failures preserve the last
+script through atomic replacement. Watch mode does not type-check; use editor
+diagnostics or `npm run check` separately. Changes to the built script,
+`manifest.json`, `assets/icon.<extension>`, or `locales/*.json` are automatically
+validated by Flare; click **Reload plugin** to apply the validated
 snapshot to this plugin's accounts and open pages. An invalid edit keeps the last
-working version running. For TypeScript projects, select your build output directory
-and run your own compiler/watch command; Flare does not execute build scripts.
+working version running. Keep the starter project root selected. Other build
+layouts must select their runtime output directory; Flare does not execute build scripts.
 
 Only one development directory can be active. Reload is refused while publishing,
 uploading, deleting, or sending is in progress; retry after the operation finishes.