afterpresets 0.0.0-stage → 0.2.0

package/runtime/docs/common/licensing.md

@@ -0,0 +1,261 @@
+---
+title: Licensing
+description: Turn licensing on, handle every license status in renderLicense, choose offline grace, test with AP.__simulate, and follow the license screen standards.
+---
+
+# Licensing
+
+The runtime owns license logic: browser sign-in, the saved license, online
+checks, device limits, and when your app may start. Your code only draws the
+license screen.
+
+## When to turn it on
+
+- **Paid extension: required.** `ap check` and `ap push` fail when a paid
+  product has no panel that boots with `license` on.
+- **Free extension: optional.** With licensing on, buyers must claim the free
+  product on AfterPresets and sign in. Leave it off unless the user
+  wants that.
+
+```js
+license: false                     // default: no license screen, start runs at once
+license: true                      // on, no offline grace
+license: { offlineGraceDays: 7 }   // on, works offline for up to 7 days
+license: { checkInBackground: false } // on, always wait for the online check (see below)
+```
+
+Buyers sign in with their AfterPresets account: the extension opens the
+browser, the buyer clicks **Sign in** on afterpresets.com, and the extension
+unlocks. The extension receives a license token that only works for
+this extension on this computer; it never sees the buyer's account
+credentials. Each panel of an extension shares one license: the buyer signs in
+once.
+
+## When the license is checked
+
+After a successful online check the API returns a signed record of it, valid
+for 12 hours, and the runtime saves it with the token. Until it runs out,
+launching the app, reloading a panel (including `ap dev` reloads) or
+opening another panel unlocks straight away, with no network call and no
+`checking` screen. After 12 hours the license is checked online again, without blocking the
+buyer:
+
+- **A panel that is already open** re-checks in the background. It stays
+  unlocked while offline and locks only if the server rejects the license (for
+  example a refund).
+- **The next launch**, with `checkInBackground` on (the default), opens the
+  app straight away and checks online behind it. If the server rejects the
+  license, the license screen appears over the app with the matching status
+  (`signed_out`, `refunded`, `not_owned`). If the buyer is offline, the normal
+  offline grace rules apply: `offline_grace` within grace, otherwise
+  `offline_expired`. Blocking the network therefore never keeps an extension
+  unlocked.
+- With `checkInBackground: false` the launch shows `checking` until the API
+  answers. Use it only if the app must not run at all before the check.
+
+Only a record signed for this extension, computer and saved sign-in counts.
+With no saved license, or one that is not signed (for example copied from
+another computer), the launch always shows `checking`. **Try again**
+(`api.retry()`) also always shows `checking`. The record is signed by
+AfterPresets, so editing the saved file does not extend it.
+
+## Offline grace
+
+`offlineGraceDays` is a whole number from 0 to 30. The default is **0**.
+Values outside the range are clamped, with a console warning.
+
+| Setting | Buyer launches the extension while offline |
+|---|---|
+| `0` (default) | Status `offline_expired`. The app does not start until the license is checked online. |
+| `1`-`30` | If the last signed online check was less than that many days ago, status `offline_grace`: the app starts and the screen should show a small warning. Otherwise `offline_expired`. |
+
+Tradeoff: grace lets buyers work on planes and in studios with no internet, but
+a refunded license keeps working offline for up to that many days.
+Ask the user; 7 days is a common choice. Never set it without telling them.
+
+## The contract
+
+```js
+AP.boot({
+  start: function (ctx) { /* your app */ },
+  license: true,
+  renderLicense: function (api, root) {
+    // Clear root, then draw api.state.status into it.
+  }
+});
+```
+
+- `renderLicense(api, root)` is called at boot and again after **every** state
+  change. Treat it as a pure render: empty `root`, then draw `api.state`.
+- `root` is `<div id="ap-license-root">`, appended to `<body>` by the runtime.
+  The runtime only sets `root.style.display` (`"none"` while `active`, `""`
+  otherwise) and the attribute `data-ap-status="<status>"`. It has no classes and
+  no styles. **Your CSS positions it**: usually a full-panel overlay, and a thin
+  bar for `offline_grace`:
+
+  ```css
+  #ap-license-root { position: fixed; top: 0; right: 0; bottom: 0; left: 0; z-index: 1000; background: #1d1d1d; }
+  #ap-license-root[data-ap-status="offline_grace"] { bottom: auto; }
+  ```
+- Do not move, remove, or set `display` on `root`. Draw only inside it.
+- If `renderLicense` throws, the runtime logs the error and keeps going.
+
+### api
+
+`api` is the same object as `AP.license` and `ctx.license`.
+
+| Member | Use |
+|---|---|
+| `api.state` | `{ status, message, graceDaysLeft, productUrl, manageDevicesUrl, signIn, account }` |
+| `api.signIn(cb?)` | Start a browser sign-in. The runtime opens the sign-in page and waits for approval. `cb(state)` once it started. |
+| `api.openSignInPage()` | Open the sign-in page again (while `signing_in`). |
+| `api.cancelSignIn()` | Stop waiting. Status becomes `signed_out`. |
+| `api.retry(cb?)` | Check the saved license online again. |
+| `api.signOut(cb?)` | Sign this computer out (all panels) and free its device slot. Status becomes `signed_out`. |
+| `api.openUrl(url)` | Open an `http(s)` URL in the default browser. |
+| `api.onChange(fn)` | `fn(state)` after each change. Returns an unsubscribe function. |
+
+`state.message` is a ready-to-show sentence (sometimes from the server).
+`state.productUrl` is the product page where buyers get the extension.
+`state.manageDevicesUrl` is where buyers remove old computers.
+`state.signIn` is `{ url }` (the sign-in page) while `signing_in`, otherwise
+`null`. There is no code to show: the buyer only approves in the browser.
+`state.account` is `{ username }` once signed in, otherwise `null`.
+
+## Every status
+
+`start` runs only for `active` and `offline_grace`. Every other status blocks the
+app, so the screen must explain what to do.
+
+| Status | What the screen shows | Controls and the api call |
+|---|---|---|
+| `disabled` | Nothing. Licensing is off; `renderLicense` is never called. | None |
+| `signed_out` | Ask the buyer to sign in (`state.message` says why after a sign-out) | **Sign in with AfterPresets** → `api.signIn()`; **Get it** → `api.openUrl(state.productUrl)` |
+| `signing_in` | "Finish signing in in your browser" (`state.message`) | **Open browser again** → `api.openSignInPage()`; **Cancel** → `api.cancelSignIn()` |
+| `checking` | Progress text (`state.message`) | Disable buttons |
+| `active` | Nothing (root is hidden). Clear `root`. | None |
+| `not_owned` | `state.message`: this account does not own the extension | **Get it** → `api.openUrl(state.productUrl)`; **Try again** → `api.retry()`; **Use a different account** → `api.signOut()` |
+| `refunded` | `state.message`: the purchase was refunded | **Get it**; **Use a different account** → `api.signOut()` |
+| `offline_grace` | One short non-blocking line with `state.graceDaysLeft` (the app is running) | **Retry** → `api.retry()` |
+| `offline_expired` | Ask the buyer to connect to the internet | **Try again** → `api.retry()`; **Use a different account** → `api.signOut()` |
+| `error` | `state.message` | **Try again** → `api.retry()`; **Sign in** → `api.signIn()` |
+
+Too many computers is handled on the website during sign-in: the buyer removes
+an old computer under **Manage devices** there, then confirms again. Show
+**Manage devices** → `api.openUrl(state.manageDevicesUrl)` on the signed-in
+screens of your app (for example in settings) so buyers can find it.
+
+The labels **Sign in with AfterPresets** and **Get it** are required wording.
+`ap check` warns when your license screen code does not mention a status.
+
+## Example renderer
+
+Keep the markup in HTML, one block per status, and let the JS pick the block
+and fill in text. This is how the starter's `src/features/license-screen/`
+works (it uses the small helpers in `src/shared/lib/view.js`).
+
+```html
+<!-- src/features/license-screen/license-screen.html (shortened) -->
+<div data-state="signed_out">
+  <h1 id="license-title-signed_out">Sign in to unlock</h1>
+  <p data-field="message"></p>
+  <button type="button" data-action="signIn">Sign in with AfterPresets</button>
+  <button type="button" data-action="getIt">Get it</button>
+</div>
+<div data-state="signing_in">
+  <h1 id="license-title-signing_in">Continue in your browser</h1>
+  <p data-field="message"></p>
+  <button type="button" data-action="openSignInPage">Open browser again</button>
+  <button type="button" data-action="cancelSignIn">Cancel</button>
+</div>
+<!-- ...one block for checking, not_owned, refunded, offline_expired, error,
+     and a small banner for offline_grace -->
+```
+
+```js
+// src/features/license-screen/license-screen.js (shortened)
+import markup from "./license-screen.html";
+import { mount, isMounted, showState, fill, onAction } from "../../shared/lib/view.js";
+
+export function renderLicense(api, root) {
+  if (!isMounted(root)) {
+    mount(root, markup);  // the project's own HTML file, never outside data
+    onAction(root, {
+      signIn: function () { api.signIn(); },
+      openSignInPage: function () { api.openSignInPage(); },
+      cancelSignIn: function () { api.cancelSignIn(); },
+      retry: function () { api.retry(); },
+      signOut: function () { api.signOut(); },
+      getIt: function () { api.openUrl(api.state.productUrl); }
+    });
+  }
+  var s = api.state;
+  showState(root, s.status);  // "active" matches no block: nothing shows
+  fill(root, { message: s.message });  // textContent
+}
+```
+
+## Hard rules
+
+1. Never call `start` yourself and never show app UI from `renderLicense`.
+2. Never read, log, or send the saved license file or token. The runtime keeps
+   the only copy and sends it only to AfterPresets.
+3. Never ask the buyer for a password or key. Sign-in always happens in the
+   browser through `api.signIn()`.
+4. Never call the AfterPresets API directly for licensing. Use `api.*`.
+5. Open links only with `api.openUrl(url)`, using the URLs in `api.state`. Do
+   not hard-code them.
+6. Handle every status in the table.
+7. Do not style or hide `#ap-license-root` so the app is usable while blocked.
+8. Insert text with `textContent` (`fill`), never `innerHTML`: `state.message`
+   can come from the server. `innerHTML` is only for your own `.html` files.
+
+## UI standards
+
+**Accessibility**
+
+- Use real `<button>` elements.
+- Put `state.message` in an element with `role="status"` (`role="alert"` for
+  error statuses) so screen readers announce changes.
+- Give the blocking screen a heading. Move focus to the main button.
+- While `signing_in`, say plainly that the next step happens in the browser,
+  and keep **Open browser again** visible in case the tab was closed.
+- Keep a visible focus outline and text contrast of at least 4.5:1.
+- Fit a 300 px wide panel with no horizontal scroll.
+
+**CEP browser limits** (Chromium 74 in CEP 10)
+
+- No CSS `gap` on flex layouts (it is ignored). Use margins:
+  `.row > * + * { margin-left: 8px; }`. Grid `gap` is fine.
+- No `:has()`, `:is()`, `:where()`, `aspect-ratio`, `inset`, container queries,
+  or `?.` / `??` in JavaScript.
+- Links: `<a href>` does not open the browser in CEP. Use buttons that call
+  `api.openUrl(url)`.
+
+**Style**
+
+- Match the rest of the extension. Prefix classes with your own namespace
+  (for example `license__`); the runtime uses none.
+
+## Testing with AP.__simulate
+
+`AP.__simulate` works only in dev builds (`ap dev`) and only when licensing is
+on. It drives `renderLicense` through a status without touching the saved
+license and never calls `start`. While it is on, real license results do not
+change the screen. Run it in the live panel's console or through the
+debugging connection.
+
+```js
+AP.__simulate();                                       // lists every status
+AP.__simulate("signing_in");                           // shows code ABCD-EFGH
+AP.__simulate("offline_grace", { graceDaysLeft: 1 });
+AP.__simulate("error", { message: "Custom message" });
+AP.__simulate(false);                                  // end; validate for real
+```
+
+Before you finish, simulate every status, screenshot each one, and check that:
+
+- the required controls are present and the links open the right pages;
+- `offline_grace` leaves the app usable;
+- every other status except `active` covers the app;
+- `ap check` reports no missing statuses.

package/runtime/docs/common/panels.md

@@ -0,0 +1,114 @@
+---
+title: Panels and events
+description: Build extensions with several panels, modals, or invisible panels; open and close them with AP.panels; send data between them with AP.events.
+---
+
+# Panels and events
+
+One extension can have several windows. Each is a **panel** with its own id,
+HTML, and JavaScript. They share `js/`, `css/`, `jsx/`, and the license.
+
+## Panel types
+
+| `type` | What it is | Use it for |
+|---|---|---|
+| `panel` | A dockable panel, listed in **Window → Extensions** when `menu` is true | The main UI |
+| `modal` | A dialog that blocks the app until closed | Settings, confirmations, one-off forms |
+| `invisible` | No window; starts with the app and runs in the background | Listening for events, background work |
+
+Panels are declared in `afterpresets.json`:
+
+```json
+"panels": [
+  { "id": "main", "title": "Tool", "type": "panel", "width": 400, "height": 580, "menu": true },
+  { "id": "settings", "title": "Tool Settings", "type": "modal", "width": 360, "height": 300 }
+]
+```
+
+## Adding a panel
+
+```sh
+ap add panel settings --type modal
+ap add panel worker --type invisible
+ap add panel inspector --title "Inspector" --width 320 --height 480
+```
+
+This creates `src/panels/<id>/index.html` and `src/panels/<id>/main.js`, and
+adds the entry to `afterpresets.json`. Each panel calls `AP.boot` in its own
+`main.js` and imports the screens and helpers it uses from `src/features/`
+and `src/shared/`. After adding a panel, restart
+`ap dev` and then the app: CEP reads the manifest only at launch.
+
+## AP.panels
+
+```js
+AP.panels.current();          // { id: "main" } - also ctx.panel
+AP.panels.open("settings");   // open another panel of this extension
+AP.panels.close();            // close this panel
+AP.panels.close("settings");  // ask another open panel to close itself
+```
+
+- Ids are the ones in `afterpresets.json`. An invalid id throws.
+- `open` asks the app to open the extension `<bundleId>.<id>`. It returns
+  `true` when the request was sent; it does not wait for the panel to load.
+- Data cannot be passed to `open`. Send it with `AP.events` once the other
+  panel is ready (see "Handshake" below).
+
+## AP.events
+
+`AP.events` sends JSON messages between the open panels of this extension.
+
+```js
+var off = AP.events.on("preset:selected", function (data, meta) {
+  // data: the JSON value that was sent. meta.from: the sender's panel id.
+  showPreset(data.name);
+});
+
+AP.events.emit("preset:selected", { name: "Bounce" });   // returns true if sent
+
+off();                                        // stop listening
+AP.events.off("preset:selected", handler);   // same, by function
+```
+
+- Delivered to every **other** open panel that listens to that name. The
+  sending panel does not receive its own event.
+- `data` must be JSON-serialisable (objects, arrays, strings, numbers,
+  booleans, `null`). Delivery is asynchronous.
+- Names use letters, digits, and `_ . : -` (up to 100 characters). Names
+  starting with `__ap.` are reserved and throw.
+- A panel that is not open receives nothing; events are not queued.
+
+### Handshake: send data to a panel you just opened
+
+```js
+// src/panels/main/main.js
+AP.events.on("settings:ready", function () {
+  AP.events.emit("settings:load", { fps: 24 });
+});
+AP.panels.open("settings");
+
+// src/panels/settings/main.js (inside start)
+AP.events.on("settings:load", function (data) { renderForm(data); });
+AP.events.emit("settings:ready", null);
+```
+
+## Shared license
+
+All panels of an extension share one saved license. The buyer activates once.
+
+- When a panel opens, it validates the saved key; it does not ask again.
+- When the buyer activates or signs out in one panel, every other open panel
+  updates itself automatically.
+- Every panel that boots with `license` on needs its own `renderLicense`. A
+  small modal can reuse the main panel's license screen code from `js/`.
+- An `invisible` panel cannot show a license screen. Boot it with licensing
+  on and a `renderLicense` that draws nothing; its `start` runs once the buyer
+  has activated in a visible panel.
+
+## Updates with several panels
+
+Every panel with `updates.check: "auto"` checks for updates. Only one install
+runs at a time, and `onInstalled` fires in every open panel. `AP.updates.reload()`
+reloads every open panel of the extension, so one **Reload now** click starts
+the new version everywhere. To keep it simple, show the update screen in the
+main panel and use `updates: { check: "manual" }` in the others.

package/runtime/docs/common/storage.md

@@ -0,0 +1,82 @@
+---
+title: Saving data
+description: Where an extension keeps settings and other local state with AP.storage and AP.paths.data(), what goes inside the app's project file instead, and what never to store.
+---
+
+# Saving data
+
+## Where each kind of data goes
+
+| Data | Where |
+|---|---|
+| Settings, preferences, recent items, small caches | `AP.storage` (below) |
+| Bigger files you create or download (images, media, generated presets) | A file in `AP.paths.data()` |
+| Data that belongs to one After Effects or Premiere Pro project | Inside the `.aep` / `.prproj`, from `jsx/` (it travels with the project file) |
+| Secrets (passwords, API keys, tokens) | Nowhere. Everything above is a plain file the user can open. |
+
+Do **not** use `localStorage`, `sessionStorage` or IndexedDB: in CEP each panel
+gets its own copy (so panels do not share it), and it lives in a cache folder
+that can be cleared. Never write into the extension folder
+(`AP.paths.extension()`): every update replaces it.
+
+## AP.storage
+
+Small JSON values, kept on this computer across launches and updates, shared
+by every panel of this extension.
+
+```js
+var settings = AP.storage.get("settings", { fps: 24, autoApply: false }); // fallback until saved
+settings.fps = 30;
+AP.storage.set("settings", settings);    // true when saved
+
+AP.storage.remove("settings");           // or AP.storage.set("settings", undefined)
+AP.storage.keys();                       // ["recent", "settings"]
+```
+
+| Call | Does |
+|---|---|
+| `get(key, fallback)` | The saved value, or `fallback` when nothing is saved (or the file is unreadable). |
+| `set(key, value)` | Saves any JSON value (objects, arrays, strings, numbers, booleans, `null`). Returns `true`, or `false` if the disk write failed. |
+| `remove(key)` | Deletes the value. |
+| `keys()` | Saved keys, sorted. |
+| `onChange(key, fn)` | `fn(value)` runs when **another** open panel of this extension sets or removes `key` (`value` is `undefined` after a remove). Returns a function that stops listening. |
+
+- Keys use letters, digits, `_`, `.` and `-` (up to 100 characters, not
+  starting with `.` or `-`). An invalid key throws.
+- A value is limited to 1 MB; functions, cyclic objects and other values JSON
+  cannot hold throw. Store bigger data as a file in `AP.paths.data()`.
+- Each key is its own file, written atomically, so a crash never leaves a
+  half-saved value and two panels saving different keys never overwrite each
+  other. If two panels save the same key, the last one wins.
+- `get` returns a fresh copy from disk: change it, then `set` it again.
+
+Keep a panel in sync when the settings modal saves:
+
+```js
+// src/panels/main/main.js
+AP.storage.onChange("settings", function (settings) {
+  applySettings(settings || DEFAULTS);
+});
+```
+
+## Files: AP.paths.data()
+
+`AP.paths.data()` returns a folder that exists, belongs to this extension, and
+survives updates (`.../AfterPresets/extensions/<bundleId>/app/`). Use Node's
+`fs` and `path` there for anything that is not a small JSON value:
+
+```js
+var fs = require("fs");
+var path = require("path");
+var file = path.join(AP.paths.data(), "thumbnails", "intro.png");
+```
+
+Pass such paths to ExtendScript as arguments when the app needs them
+(see [assets.md](assets.md)).
+
+## Inside the project file
+
+Data about one project (which presets it uses, a layout you applied) belongs in
+the project, not on the computer: it should follow the `.aep` or `.prproj` to another
+machine. Read and write it from a `jsx/` function, for example in a project
+XMP field or on a layer or comp comment, and call it with `ctx.host.eval`.