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

package/README.md

@@ -13,6 +13,7 @@ With Node 22 or newer, run:
 ```sh
 npx flare-plugin-sdk@next init my-plugin
 cd my-plugin
+npm install
 ```
 
 This copies the GitHub template bundled with that SDK version into `my-plugin`:
@@ -22,6 +23,11 @@ my-plugin/
   manifest.json
   plugin.js
   assets/icon.png
+  src/plugin.ts
+  package.json
+  tsconfig.json
+  build.mjs
+  .gitignore
   README.md
 ```
 
@@ -38,11 +44,15 @@ used to create it. Open it in VS Code or another JSON Schema editor for property
 completion, descriptions, enum choices, and static validation. The complete schema
 is bundled at `skill/flare-plugin/manifest.schema.json` inside the SDK.
 
-Edit `plugin.js` to use your website's real authentication, endpoints, response
+The root already contains an installable, prebuilt `plugin.js`. Install development
+dependencies to edit and rebuild the TypeScript source. The private project pins
+the SDK to the version used by `init`; TypeScript and esbuild are development tools.
+
+Edit `src/plugin.ts` to use your website's real authentication, endpoints, response
 mapping, and pagination. The starter's `/api/me` and `/api/posts` are illustrative;
 no demonstration server is included. Update the description, login methods and
-capabilities in `manifest.json`, and replace the placeholder icon. The plain
-JavaScript starter needs no dependency installation or build step.
+capabilities in `manifest.json`, and replace the placeholder icon. Keep `plugin.js`
+as generated output; edit the TS source and rebuild instead of editing both copies.
 
 For manual template copies, replace the example IDs and names before use. For
 `npx` projects, keep the generated IDs. Read the
@@ -51,13 +61,16 @@ for authentication, Host APIs, capabilities, and Wire data mapping.
 
 ## Develop and debug in Flare
 
-1. From `my-plugin`, check the source syntax:
+1. From `my-plugin`, run:
 
    ```sh
-   node --check plugin.js
+   npm run check
+   npm run build
    node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
    ```
 
+   `check` uses the SDK's ambient types with strict TypeScript checking. `build`
+   checks types and bundles local TS modules into one ES2020 IIFE at root.
    Actual execution and manifest/registration validation happen in Flare, which
    provides `definePlugin` and `flare`.
 2. In Compose Desktop or native macOS, open **Settings → Plugins → More → Plugin
@@ -67,8 +80,11 @@ for authentication, Host APIs, capabilities, and Wire data mapping.
    website's HTTPS API origin, and import a real access token using the starter's
    login form. Adapt this step if you change the login method. Test login,
    timeline refresh, older pages, end-of-list behavior, and website link clicks.
-4. Edit and save the files. Flare automatically validates changes; click **Reload
-   plugin** to apply the validated version. Invalid edits keep the last working
+4. Run `npm run dev` in a terminal, then edit `src/plugin.ts` or its local modules.
+   Watch mode rebuilds `plugin.js`; syntax/build errors preserve the previous
+   script. It transpiles without type checking, so use editor diagnostics or run
+   `npm run check` separately. Flare automatically validates runtime-file changes;
+   click **Reload plugin** to apply them. Invalid edits keep the last working
    version running. The development panel shows validation errors and recent-call
    diagnostics; recent calls contain method names and outcomes, without HTTP
    request/response payloads.
@@ -78,8 +94,8 @@ for authentication, Host APIs, capabilities, and Wire data mapping.
    Development uses real accounts and data, and remote writes are not rolled back.
 
 Finish active writes before reloading; credential-schema changes may require
-logging in again. For TypeScript, run your own compiler/watch command and
-select its output directory; Flare loads one self-contained classic `plugin.js`.
+logging in again. Keep Flare pointed at the project root, where the build writes
+`plugin.js`. Flare loads that classic script and does not execute TS or build tools.
 See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop).
 
 ## Publish and install through GitHub (recommended)
@@ -89,12 +105,15 @@ See [development and testing details](https://github.com/DimensionDev/Flare/blob
    and optional `locales/*.json`. Update the project README with the actual website,
    login instructions, supported features, and verification results. Flare reads
    these files directly; commit any compiled output at the root before tagging.
-2. Commit and push the plugin files. For a new project and an empty GitHub
+2. Run `npm run build`, then commit both source and the resulting root `plugin.js`.
+   The generated `.gitignore` excludes dependencies, temporary files and `.fpp`
+   archives, while retaining `plugin.js`. Commit the `package-lock.json` created
+   by `npm install`; use `npm ci` on later clean checkouts. For a new project and an empty GitHub
    repository, replace `OWNER/REPO` and run from `my-plugin`:
 
    ```sh
    git init
-   git add manifest.json plugin.js assets README.md
+   git add manifest.json plugin.js assets src package.json package-lock.json tsconfig.json build.mjs .gitignore README.md
    # If used, also stage translations with: git add locales
    git commit -m "Add Flare plugin"
    git branch -M main
@@ -130,23 +149,33 @@ See [GitHub publication and update rules](https://github.com/DimensionDev/Flare/
 ## Optional: package and install a local file
 
 Use `.fpp` for offline transfer or local testing when GitHub distribution is not
-needed. From your project, create a new, empty `dist` directory and copy only
-`manifest.json`, `plugin.js`, one `assets/icon.<extension>`, and any `locales/*.json`
-into it, preserving those paths. Keep source, `.git`, `package.json`, `node_modules`,
-and previous archives outside `dist`. Then run from the project root:
+needed. From the generated project root:
 
 ```sh
-npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+npm run package
 ```
 
+This checks types, rebuilds `plugin.js`, stages only manifest/script/icon/locale
+files in a temporary directory, reuses the SDK packer, and writes `plugin.fpp` in
+the project root. Temporary staging is cleaned up. Source and development files
+are excluded. The standalone `flare-plugin-pack` command still requires a clean
+runtime directory; passing the entire TS project is not supported.
+
 Stop development for this plugin. In **Settings → Plugins → Add**, choose file
 installation, select the `.fpp`, review, and confirm. Installation is immediate.
 Packaging checks archive structure; Flare still validates the manifest,
 registration, permissions, and behavior. File installs have no GitHub update tracking.
 
-## Optional: editor types and TypeScript
+## SDK types and editor support
+
+The generated `tsconfig.json` already sets `types: ["flare-plugin-sdk"]`, strict
+checking, and an ES2020 library without browser or Node globals. `definePlugin`
+contextually types its handlers; `PostV1`, `ProfileV1`, and other SDK types are
+available directly. The SDK is a development dependency, not a runtime import.
+Local TS imports are bundled into `plugin.js`; imported code must also work
+without Node/browser APIs. `build` and `package` stop on type errors.
 
-For JSON Schema use without network access, install the SDK below and set the
+For JSON Schema use without network access, install the project's dependencies and set the
 manifest's `$schema` to `./node_modules/flare-plugin-sdk/skill/flare-plugin/manifest.schema.json`.
 Keep these development files outside the optional `.fpp` staging directory.
 Flare treats `$schema` as editor metadata and never downloads it. With an older
@@ -155,7 +184,7 @@ association in workspace settings instead. See the
 [manifest editor guide](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/manifest.md#json-schema-and-editor-support)
 and [VS Code schema settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings).
 
-Install editor types in your authoring project:
+For an existing project, install editor types:
 
 ```sh
 npm install --save-dev flare-plugin-sdk@next
@@ -191,7 +220,11 @@ All documentation is in English. The complete Pixelfed adapter is bundled at
 From `feature/plugin/sdk`, run `npm ci` and `npm test` with Node 22 or newer.
 The tests build an npm tarball, check its complete resource set and license,
 install it offline in an empty project, invoke the actual npx initializer,
-type-check a consumer, and package both the generated project and bundled template.
+type-check a consumer, and install/build/package the generated TS project. The
+SDK tarball is installed offline; development tools use cached packages where
+available and fetch missing npm metadata or packages. Checks compare the built and
+prebuilt script, exercise local-module bundling, watch errors/recovery and missing
+Node APIs, and verify the package contains only runtime files.
 Initializer tests cover valid unique IDs, empty/nested/Unicode paths, invalid
 arguments, and preserving existing directories, files, and symlinks. They do not
 contact a website or publish to npm. Flare's Host and platform acceptance checks are

package/bin/cli.mjs

@@ -39,20 +39,24 @@ async function main() {
   manifest.name = name;
   manifest.platform.id = `Plugin${identity}`;
   manifest.platform.name = name;
+  const project = JSON.parse(await readFile(join(template, "package.json"), "utf8"));
+  project.name = manifest.id;
+  project.devDependencies["flare-plugin-sdk"] = version;
 
   await mkdir(target, { recursive: true });
   for (const entry of await readdir(template)) {
-    if (entry === "manifest.json") continue;
-    await cp(join(template, entry), join(target, entry), {
+    if (["manifest.json", "package.json"].includes(entry)) continue;
+    await cp(join(template, entry), join(target, entry === "_gitignore" ? ".gitignore" : entry), {
       recursive: true,
       force: false,
       errorOnExist: true,
     });
   }
   await writeFile(join(target, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+  await writeFile(join(target, "package.json"), `${JSON.stringify(project, null, 2)}\n`, { flag: "wx" });
 
   console.log(`Created ${target}\nPlugin ID: ${manifest.id}\nPlatform ID: ${manifest.platform.id}`);
-  console.log("Adapt the example API in plugin.js and README.md, then load this directory in Flare's Plugin development.");
+  console.log("Run npm install, edit src/plugin.ts, and use npm run dev to update plugin.js. Load this directory in Flare's Plugin development.");
 }
 
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flare-plugin-sdk",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "description": "Types, tooling, templates and authoring references for Flare plugins",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/DimensionDev/Flare#plugins-beta",
@@ -33,6 +33,7 @@
   },
   "devDependencies": {
     "ajv": "8.20.0",
+    "esbuild": "0.28.2",
     "typescript": "6.0.3"
   }
 }

package/skill/flare-plugin/README.md

@@ -168,10 +168,12 @@ cases matter. It should identify gaps rather than invent website endpoints.
    cd my-plugin
    ```
 
-   It generates unique plugin/platform IDs and needs no dependency installation
-   or build step for plain JavaScript. For manual copies of
+   It generates a TS project with SDK types and unique plugin/platform IDs. A
+   prebuilt root `plugin.js` makes it installable before dependencies are installed.
+   Run `npm install`, edit `src/plugin.ts`, and use `npm run dev` while developing;
+   `npm run build` checks types before rebuilding the root script. For manual copies of
    [assets/github-template](assets/github-template/README.md), replace its example
-   IDs and names first. The example API needs adaptation; no demonstration server
+   IDs and names first and rename `_gitignore` to `.gitignore`. The example API needs adaptation; no demonstration server
    is provided.
 2. Keep the generated IDs stable, replace the placeholder icon, and adapt
    authentication and data mapping to your website. See [manifest](references/manifest.md)
@@ -183,8 +185,9 @@ cases matter. It should identify gaps rather than invent website endpoints.
    to start the local directory, test an account, and apply saved edits with
    **Reload plugin** after automatic validation. Follow the syntax, behavior and
    platform checks. Stop development before installing/updating the same plugin.
-5. Prefer GitHub distribution: commit the ready-to-run files at a public repository
-   root, then push a stable tag matching `manifest.version`. In Flare's plugin
+5. Prefer GitHub distribution: run `npm run build`, commit the TS source, build
+   configuration, lockfile and root `plugin.js`, then push a stable tag matching
+   `manifest.version`. In Flare's plugin
    management, enter `https://github.com/OWNER/REPO` and click **Install**. Review
    source and permissions, then confirm to use the plugin immediately. Follow the
    plugin's README to select the platform, origin, and login method.

package/skill/flare-plugin/SKILL.md

@@ -29,8 +29,13 @@ to the user's plugin repository.
 
 ## Implement the requested adapter
 
-Start a new repository from [the GitHub template](assets/github-template/README.md).
-Copy the **contents** of `assets/github-template/` to the new repository root.
+Start with `npx flare-plugin-sdk@next init my-plugin` and follow the
+[project workflow](assets/github-template/README.md). For manual copies, put the
+**contents** of `assets/github-template/` at root, replace example IDs and rename
+`_gitignore` to `.gitignore`. Install development dependencies, edit `src/plugin.ts`
+using the ambient SDK types, and run `npm run build`. Commit the resulting root
+`plugin.js` with the TS source and lockfile. `npm run dev` watches without type
+checking; `npm run check` and the type-checked build are the release gates.
 Its `/api/me` and `/api/posts` contract is illustrative, not a live service. Adapt
 it from verified website evidence before presenting it as an integration.
 Use [Pixelfed](examples/pixelfed/README.md) as a complete real-service example,

package/skill/flare-plugin/assets/github-template/README.md

@@ -12,6 +12,7 @@ If you created this project with `npx flare-plugin-sdk@next init my-plugin`, wor
 inside `my-plugin` and keep its generated plugin/platform IDs. If you copied the
 template manually, first copy its contents to your repository root and replace
 the example `manifest.id`, `platform.id`, and names. Keep IDs stable for updates.
+For manual copies, also rename `_gitignore` to `.gitignore`; `init` does this for you.
 
 The generated manifest's `$schema` is pinned to the SDK version that created it.
 Open `manifest.json` in VS Code or another JSON Schema editor for completion,
@@ -22,7 +23,7 @@ for offline use and older Flare builds that reject `$schema`.
 
 1. Update the description, login methods, and declared capabilities in
    `manifest.json`. Replace the one-pixel placeholder PNG with your own icon.
-2. Adapt `plugin.js` using the
+2. Adapt `src/plugin.ts` using the
    [developer guide](https://github.com/DimensionDev/Flare/tree/feature/plugin/feature/plugin/sdk/skill/flare-plugin)
    and your website's API evidence.
    It currently verifies an imported bearer token with `/api/me`, then reads
@@ -37,14 +38,23 @@ authenticated profile returned at login supplies the saved account identity.
 
 ## 2. Develop and debug locally
 
-The plain JavaScript starter needs Node 22 or newer for tooling, with no dependency
-installation or build step. From this project directory, check syntax:
+The root contains a prebuilt, installable `plugin.js`, alongside TS source and
+development tools. With Node 22 or newer, run from this project directory:
 
 ```sh
-node --check plugin.js
+npm install
+npm run check
+npm run build
 node -e 'JSON.parse(require("node:fs").readFileSync("manifest.json", "utf8")); console.log("Manifest JSON parses")'
 ```
 
+`npm install` creates a lockfile; commit it and use `npm ci` on later checkouts.
+The private package uses the SDK for ambient types, TypeScript for strict checking,
+and esbuild to bundle local TS modules into one ES2020 IIFE at root. The generated
+SDK dependency is version-pinned. Types such as `PostV1`, `ProfileV1`, and
+`PluginErrorCodeV1` are available directly, and `definePlugin` types its handlers.
+The SDK is not imported at runtime; plugin code has no Node or browser globals.
+
 Flare supplies the `definePlugin` and `flare` globals and performs the actual
 manifest, registration, and runtime checks. Use a Flare build with Plugins in Settings.
 
@@ -54,9 +64,12 @@ manifest, registration, and runtime checks. Use a Flare build with Plugins in Se
 2. Add an account, explicitly select this plugin platform, and enter your website's
    HTTPS API origin. Import a real access token. After adapting the endpoints,
    verify the account identity, Home refresh, older/empty/end pages, and link clicks.
-3. Edit and save `plugin.js`, `manifest.json`, the icon, or translations. Flare
-   automatically validates them; click **Reload plugin** to apply the validated
-   version. Invalid edits leave the previous working version running.
+3. Run `npm run dev` and edit `src/plugin.ts` or its local modules. Watch mode
+   rebuilds `plugin.js`, preserving the previous script on syntax/build errors.
+   It does not check types; use editor diagnostics or `npm run check` separately.
+   Flare automatically validates the built script, manifest, icon and translations;
+   click **Reload plugin** to apply the validated version. Invalid changes leave
+   the previous working version running.
 4. Check validation errors and recent-call diagnostics in the development panel.
    Recent calls show method names and outcomes, without HTTP request/response
    payloads. Reproduce authentication, HTTP, response-mapping, and paging failures
@@ -66,9 +79,9 @@ manifest, registration, and runtime checks. Use a Flare build with Plugins in Se
    automatically mount this directory. Development uses real accounts and data,
    and remote writes are not rolled back.
 
-For TypeScript, run your own compiler/watch process and select its output directory.
-Emit one self-contained classic `plugin.js`; Flare provides its Host APIs rather
-than Node/browser APIs. Commit that built script at the repository root for release.
+Keep the project root selected in Flare. Edit TS source, not the generated
+`plugin.js`; `npm run build` checks types before rebuilding it. Commit that built
+script at root so GitHub installation works without running npm on the device.
 See [development and testing details](https://github.com/DimensionDev/Flare/blob/feature/plugin/feature/plugin/sdk/skill/flare-plugin/references/testing.md#develop-locally-in-desktop)
 for reload restrictions, credential changes, and platform acceptance checks.
 
@@ -87,13 +100,16 @@ locales/en.json       # optional; other locale catalogs as needed
 The icon can also be JPEG, WebP, GIF, or ICO; keep exactly one supported icon.
 Development files may coexist in the repository, but keep credentials,
 `node_modules`, build caches, and private fixtures out of Git. Flare reads the
-committed plugin files directly, so build TypeScript before committing/tagging.
+committed plugin files directly. Run `npm run build` before committing/tagging;
+it must pass and the latest `plugin.js` must be committed. Keep the TS source,
+build configuration and lockfile in Git too. `.gitignore` excludes dependencies
+and local archives while retaining the runtime script.
 
 For a new project and an empty GitHub repository, replace `OWNER/REPO` and run:
 
 ```sh
 git init
-git add manifest.json plugin.js assets README.md
+git add manifest.json plugin.js assets src package.json package-lock.json tsconfig.json build.mjs .gitignore README.md
 # If used, also stage translations with: git add locales
 git commit -m "Add Flare plugin"
 git branch -M main
@@ -125,16 +141,17 @@ review/confirm the new version. See the
 
 ## Alternative: package a local file
 
-Use `.fpp` for offline transfer or local testing. Create a new, empty `dist`
-directory and copy only `manifest.json`, `plugin.js`, one supported
-`assets/icon.<extension>`, and any `locales/*.json` into it, keeping those paths.
-Keep `.git`, `package.json`, `node_modules`, tests, and old archives outside `dist`.
-From this project directory, run:
+Use `.fpp` for offline transfer or local testing. From this project directory:
 
 ```sh
-npx --package=flare-plugin-sdk@next flare-plugin-pack ./dist ../my-plugin.fpp
+npm run package
 ```
 
+This checks types, rebuilds the root script, copies only manifest/script/icon/locale
+files to temporary staging, and uses the SDK packer to write `plugin.fpp` at root.
+Staging is cleaned up and development files are excluded. The standalone packer
+still accepts only a clean runtime directory, not this whole project.
+
 Stop development for this plugin, then choose file installation in **Settings →
 Plugins → Add**, select the `.fpp`, review, and confirm. It becomes available
 immediately. The packer checks archive structure; Flare still validates the

package/skill/flare-plugin/assets/github-template/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.fpp
+.DS_Store
+.plugin-build-*/

package/skill/flare-plugin/assets/github-template/build.mjs

@@ -0,0 +1,76 @@
+import { execFileSync } from "node:child_process";
+import { cp, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, context } from "esbuild";
+
+const root = fileURLToPath(new URL(".", import.meta.url));
+const mode = process.argv[2];
+if (process.argv.length > 3 || (mode && !["--watch", "--package"].includes(mode))) {
+  throw new Error("Usage: node build.mjs [--watch|--package]");
+}
+const options = {
+  absWorkingDir: root,
+  entryPoints: ["src/plugin.ts"],
+  outfile: "plugin.js",
+  bundle: true,
+  format: "iife",
+  platform: "neutral",
+  mainFields: ["module", "main"],
+  target: "es2020",
+  logLevel: "info",
+  write: false,
+  plugins: [{
+    name: "plugin-output",
+    setup(builder) {
+      builder.onEnd(async (result) => {
+        if (result.errors.length) return;
+        if (result.outputFiles.length !== 1) throw new Error("A plugin build must emit one JavaScript file");
+        const temporary = await mkdtemp(join(root, ".plugin-build-"));
+        try {
+          // Preserve the installable script while edits are invalid or a build is interrupted.
+          await writeFile(join(temporary, "plugin.js"), result.outputFiles[0].contents, { flag: "wx" });
+          await rename(join(temporary, "plugin.js"), join(root, "plugin.js"));
+        } finally {
+          await rm(temporary, { recursive: true, force: true });
+        }
+      });
+    },
+  }],
+};
+
+if (mode === "--watch") {
+  const watcher = await context(options);
+  await watcher.watch();
+} else {
+  await build(options);
+  if (mode === "--package") {
+    const staging = await mkdtemp(join(tmpdir(), "flare-plugin-package-"));
+    try {
+      for (const name of ["manifest.json", "plugin.js"]) {
+        await cp(join(root, name), join(staging, name));
+      }
+      await mkdir(join(staging, "assets"));
+      for (const name of await readdir(join(root, "assets"))) {
+        if (/^icon\.(?:png|jpe?g|webp|gif|ico)$/.test(name)) {
+          await cp(join(root, "assets", name), join(staging, "assets", name));
+        }
+      }
+      const catalogs = await readdir(join(root, "locales")).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+        return [];
+      });
+      if (catalogs.length) {
+        await mkdir(join(staging, "locales"));
+        for (const name of catalogs.filter((name) => name.endsWith(".json"))) {
+          await cp(join(root, "locales", name), join(staging, "locales", name));
+        }
+      }
+      const packer = fileURLToPath(import.meta.resolve("flare-plugin-sdk/skill/flare-plugin/pack.mjs"));
+      execFileSync(process.execPath, [packer, staging, join(root, "plugin.fpp")], { stdio: "inherit" });
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+}

package/skill/flare-plugin/assets/github-template/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "flare-plugin",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "npm run check && node build.mjs",
+    "dev": "node build.mjs --watch",
+    "package": "npm run check && node build.mjs --package"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2",
+    "flare-plugin-sdk": "next",
+    "typescript": "6.0.3"
+  }
+}

package/skill/flare-plugin/assets/github-template/plugin.js

@@ -1,108 +1,114 @@
-// Adapt the illustrative website contract in README.md before publication.
-definePlugin({
-  login: {
-    token: {
-      async begin(request, context) {
-        const token = request.values.token && request.values.token.trim();
-        if (!token) fail("Validation", "Enter an access token");
-        const profile = mapProfile(await requestJson(context.origin + "/api/me", token), context);
-        return {
-          type: "success",
-          value: {
-            accountId: profile.key.id,
-            origin: context.origin,
-            credential: { accessToken: token },
-            profile,
-            capabilities: { "flare.datasource.timeline/v1": ["page"] },
-          },
-        };
-      },
-    },
-  },
-  capabilities: {
-    timeline: {
-      async page(request, context) {
-        if (request.timelineId !== "home") fail("Unsupported", "Unknown timeline");
-        const credential = await flare.credential.read();
-        if (!credential || typeof credential !== "object" || Array.isArray(credential) ||
-            typeof credential.accessToken !== "string" || !credential.accessToken) {
-          fail("AuthenticationRequired", "Import your access token again");
-        }
-        let url = context.origin + "/api/posts?limit=" + request.page.limit;
-        if (request.page.direction !== "refresh" && request.page.cursor) {
-          url += "&cursor=" + encodeURIComponent(request.page.cursor);
+"use strict";
+(() => {
+  // src/plugin.ts
+  definePlugin({
+    login: {
+      token: {
+        async begin(request, context) {
+          const token = request.values.token?.trim();
+          if (!token) fail("Validation", "Enter an access token");
+          const profile = mapProfile(await requestJson(context.origin + "/api/me", token), context);
+          return {
+            type: "success",
+            value: {
+              accountId: profile.key.id,
+              origin: context.origin,
+              credential: { accessToken: token },
+              profile,
+              capabilities: { "flare.datasource.timeline/v1": ["page"] }
+            }
+          };
         }
-        const data = await requestJson(url, credential.accessToken);
-        if (!Array.isArray(data.items)) fail("InvalidResponse", "Expected a post array");
-        if (data.next_cursor != null && (typeof data.next_cursor !== "string" || !data.next_cursor)) {
-          fail("InvalidResponse", "Expected a non-empty cursor or null");
-        }
-        return {
-          items: data.items.map(post => ({
-            key: { id: requiredString(post && post.id), host: accountHost(context) },
-            author: mapProfile(post.author, context),
-            createdAt: requiredString(post.created_at),
-            content: { format: "plain", value: requiredString(post.text) },
-            detailType: "link",
-            url: requiredString(post.url),
-          })),
-          olderCursor: data.next_cursor,
-          endReached: data.next_cursor == null,
-        };
-      },
+      }
     },
-  },
-});
-
-function accountHost(context) {
-  return context.origin.slice("https://".length);
-}
-
-function mapProfile(value, context) {
-  return {
-    key: { id: requiredString(value && value.id), host: accountHost(context) },
-    handle: requiredString(value.username),
-    displayName: requiredString(value.name),
-  };
-}
-
-function requiredString(value) {
-  if (typeof value !== "string" || !value.trim()) fail("InvalidResponse", "Missing required text field");
-  return value;
-}
-
-async function requestJson(url, token) {
-  let response;
-  try {
-    response = await flare.http.request({ url, authorization: { type: "bearer", token } });
-  } catch (error) {
-    if (error && error.code === "host.unavailable") fail("Network", "The request could not be completed");
-    throw error;
+    capabilities: {
+      timeline: {
+        async page(request, context) {
+          if (request.timelineId !== "home") fail("Unsupported", "Unknown timeline");
+          const credential = await flare.credential.read();
+          if (!credential || typeof credential !== "object" || Array.isArray(credential) || typeof credential.accessToken !== "string" || !credential.accessToken) {
+            fail("AuthenticationRequired", "Import your access token again");
+          }
+          let url = context.origin + "/api/posts?limit=" + request.page.limit;
+          if (request.page.direction !== "refresh" && request.page.cursor) {
+            url += "&cursor=" + encodeURIComponent(request.page.cursor);
+          }
+          const data = await requestJson(url, credential.accessToken);
+          if (!Array.isArray(data.items)) fail("InvalidResponse", "Expected a post array");
+          const cursor = data.next_cursor;
+          if (cursor != null && (typeof cursor !== "string" || !cursor)) {
+            fail("InvalidResponse", "Expected a non-empty cursor or null");
+          }
+          return {
+            items: data.items.map((value) => {
+              const post = requiredObject(value);
+              return {
+                key: { id: requiredString(post.id), host: accountHost(context) },
+                author: mapProfile(post.author, context),
+                createdAt: requiredString(post.created_at),
+                content: { format: "plain", value: requiredString(post.text) },
+                detailType: "link",
+                url: requiredString(post.url)
+              };
+            }),
+            olderCursor: cursor ?? void 0,
+            endReached: cursor == null
+          };
+        }
+      }
+    }
+  });
+  function accountHost(context) {
+    return context.origin.slice("https://".length);
+  }
+  function mapProfile(value, context) {
+    const profile = requiredObject(value);
+    return {
+      key: { id: requiredString(profile.id), host: accountHost(context) },
+      handle: requiredString(profile.username),
+      displayName: requiredString(profile.name)
+    };
+  }
+  function requiredString(value) {
+    if (typeof value !== "string" || !value.trim()) fail("InvalidResponse", "Missing required text field");
+    return value;
+  }
+  function requiredObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) fail("InvalidResponse", "Expected a JSON object");
+    return value;
   }
-  if (response.status === 401) fail("AuthenticationRequired", "The access token was rejected");
-  if (response.status === 404) fail("NotFound", "The requested resource was not found");
-  if (response.status === 429) {
-    const entry = Object.entries(response.headers).find(([name]) => name.toLowerCase() === "retry-after");
-    const value = entry && entry[1][0];
-    const seconds = value && /^\d+$/.test(value) ? Number(value) : undefined;
-    throw flare.error({
-      code: "RateLimited",
-      message: { value: "Try again later" },
-      retryAfterSeconds: typeof seconds === "number" && Number.isInteger(seconds) && seconds <= 604800 ? seconds : undefined,
-    });
+  async function requestJson(url, token) {
+    let response;
+    try {
+      response = await flare.http.request({ url, authorization: { type: "bearer", token } });
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "host.unavailable") {
+        fail("Network", "The request could not be completed");
+      }
+      throw error;
+    }
+    if (response.status === 401) fail("AuthenticationRequired", "The access token was rejected");
+    if (response.status === 404) fail("NotFound", "The requested resource was not found");
+    if (response.status === 429) {
+      const entry = Object.entries(response.headers).find(([name]) => name.toLowerCase() === "retry-after");
+      const value = entry?.[1][0];
+      const seconds = value && /^\d+$/.test(value) ? Number(value) : void 0;
+      throw flare.error({
+        code: "RateLimited",
+        message: { value: "Try again later" },
+        retryAfterSeconds: typeof seconds === "number" && Number.isInteger(seconds) && seconds <= 604800 ? seconds : void 0
+      });
+    }
+    if (response.status < 200 || response.status >= 300) fail("Remote", "The website returned an error");
+    let data;
+    try {
+      data = JSON.parse(response.body);
+    } catch {
+      fail("InvalidResponse", "The website did not return JSON");
+    }
+    return requiredObject(data);
   }
-  if (response.status < 200 || response.status >= 300) fail("Remote", "The website returned an error");
-  let data;
-  try {
-    data = JSON.parse(response.body);
-  } catch (_) {
-    fail("InvalidResponse", "The website did not return JSON");
+  function fail(code, message) {
+    throw flare.error({ code, message: { value: message } });
   }
-  if (!data || typeof data !== "object" || Array.isArray(data)) fail("InvalidResponse", "Expected a JSON object");
-  return data;
-}
-
-/** @param {PluginErrorCodeV1} code @param {string} message @returns {never} */
-function fail(code, message) {
-  throw flare.error({ code, message: { value: message } });
-}
+})();

package/skill/flare-plugin/assets/github-template/src/plugin.ts

@@ -0,0 +1,118 @@
+// Adapt the illustrative website contract in README.md before publication.
+definePlugin({
+  login: {
+    token: {
+      async begin(request, context) {
+        const token = request.values.token?.trim();
+        if (!token) fail("Validation", "Enter an access token");
+        const profile = mapProfile(await requestJson(context.origin + "/api/me", token), context);
+        return {
+          type: "success",
+          value: {
+            accountId: profile.key.id,
+            origin: context.origin,
+            credential: { accessToken: token },
+            profile,
+            capabilities: { "flare.datasource.timeline/v1": ["page"] },
+          },
+        };
+      },
+    },
+  },
+  capabilities: {
+    timeline: {
+      async page(request, context) {
+        if (request.timelineId !== "home") fail("Unsupported", "Unknown timeline");
+        const credential = await flare.credential.read();
+        if (!credential || typeof credential !== "object" || Array.isArray(credential) ||
+            typeof credential.accessToken !== "string" || !credential.accessToken) {
+          fail("AuthenticationRequired", "Import your access token again");
+        }
+        let url = context.origin + "/api/posts?limit=" + request.page.limit;
+        if (request.page.direction !== "refresh" && request.page.cursor) {
+          url += "&cursor=" + encodeURIComponent(request.page.cursor);
+        }
+        const data = await requestJson(url, credential.accessToken);
+        if (!Array.isArray(data.items)) fail("InvalidResponse", "Expected a post array");
+        const cursor = data.next_cursor;
+        if (cursor != null && (typeof cursor !== "string" || !cursor)) {
+          fail("InvalidResponse", "Expected a non-empty cursor or null");
+        }
+        return {
+          items: data.items.map((value: unknown): PostV1 => {
+            const post = requiredObject(value);
+            return {
+              key: { id: requiredString(post.id), host: accountHost(context) },
+              author: mapProfile(post.author, context),
+              createdAt: requiredString(post.created_at),
+              content: { format: "plain", value: requiredString(post.text) },
+              detailType: "link",
+              url: requiredString(post.url),
+            };
+          }),
+          olderCursor: cursor ?? undefined,
+          endReached: cursor == null,
+        };
+      },
+    },
+  },
+});
+
+function accountHost(context: PluginInvocationContextV1): string {
+  return context.origin.slice("https://".length);
+}
+
+function mapProfile(value: unknown, context: PluginInvocationContextV1): ProfileV1 {
+  const profile = requiredObject(value);
+  return {
+    key: { id: requiredString(profile.id), host: accountHost(context) },
+    handle: requiredString(profile.username),
+    displayName: requiredString(profile.name),
+  };
+}
+
+function requiredString(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) fail("InvalidResponse", "Missing required text field");
+  return value;
+}
+
+function requiredObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("InvalidResponse", "Expected a JSON object");
+  return value as Record<string, unknown>;
+}
+
+async function requestJson(url: string, token: string): Promise<Record<string, unknown>> {
+  let response: HttpResponseV1;
+  try {
+    response = await flare.http.request({ url, authorization: { type: "bearer", token } });
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "host.unavailable") {
+      fail("Network", "The request could not be completed");
+    }
+    throw error;
+  }
+  if (response.status === 401) fail("AuthenticationRequired", "The access token was rejected");
+  if (response.status === 404) fail("NotFound", "The requested resource was not found");
+  if (response.status === 429) {
+    const entry = Object.entries(response.headers).find(([name]) => name.toLowerCase() === "retry-after");
+    const value = entry?.[1][0];
+    const seconds = value && /^\d+$/.test(value) ? Number(value) : undefined;
+    throw flare.error({
+      code: "RateLimited",
+      message: { value: "Try again later" },
+      retryAfterSeconds: typeof seconds === "number" && Number.isInteger(seconds) && seconds <= 604800 ? seconds : undefined,
+    });
+  }
+  if (response.status < 200 || response.status >= 300) fail("Remote", "The website returned an error");
+  let data: unknown;
+  try {
+    data = JSON.parse(response.body);
+  } catch {
+    fail("InvalidResponse", "The website did not return JSON");
+  }
+  return requiredObject(data);
+}
+
+function fail(code: PluginErrorCodeV1, message: string): never {
+  throw flare.error({ code, message: { value: message } });
+}

package/skill/flare-plugin/assets/github-template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "lib": ["ES2020"],
+    "types": ["flare-plugin-sdk"],
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"]
+}

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.