@quickwatch/preview 0.2.0 → 0.3.0

package/README.api.md

@@ -0,0 +1,43 @@
+## The package
+
+`@quickwatch/preview` is QuickWatch's watch preview as one script, plus QuickWatch's validator for Node.
+
+In a page (the script from jsDelivr, `window.QuickWatch`):
+
+- **Auto-mount** (above): `<script type="application/json" data-qw-watch>` and `data-qw-data` blocks are drawn as the
+  widget whenever the script finishes loading. Pair several by value (`data-qw-watch="a"` with `data-qw-data="a"`),
+  put the widget in a `[data-qw-mount]` element, and set the site with `data-qw-origin`.
+- `QuickWatch.widget(element, watch, data, options)`: the same widget, into an element. Options: `title`, `origin`
+  (default `https://quickwatch.app`) and those of `render`.
+- `QuickWatch.render(element, watch, data, options)`: just the watch. Options: `surface` (`overview`, `tile`,
+  `complication`, `page:<id>`), `experience`, `device` (`QuickWatch.devices`), `theme` (`auto` or
+  `QuickWatch.themes`), `data` (`sample`, `loading`, `error`, `empty`, `stale`), `ambient`, `size` (CSS px across the
+  face), `frame`, `onUpdate`, `onError`. Returns `{ surfaces, surface, show(key), update(watch, data), errors,
+  destroy() }`.
+- `await QuickWatch.link(watch, data)`: the Open in QuickWatch link.
+
+`watch` and `data` are objects or JSON text (comments and trailing commas allowed). Nothing is fetched except the two
+font files next to the script; sources show their sample data and actions are simulated.
+
+The widget and the watch draw inside shadow roots (with `all: initial` on the host), so the page's styles, such as a
+chat panel's rules for buttons, links and text, cannot change them; only the two `@font-face` rules go into the page's
+`<head>`. The widget's light or dark look follows the background it sits on (`appearance: 'light' | 'dark'` to
+choose).
+
+In Node (`import { check, link } from '@quickwatch/preview'`) and the shell:
+
+- `npx @quickwatch/preview check watch.json data.json [--origin <url>] [--json]`: validates with QuickWatch's own
+  validator, prints the problems (JSON path, rule, line and column) and the Open in QuickWatch link. Exit code 1 when
+  there are errors.
+- `await check(watch, data)`: `{ issues, errors, warnings, link }`. `await link(watch, data)`: the link.
+
+Pin an exact version (`@quickwatch/preview@0.3.0`) to skip jsDelivr's redirect from `@0`.
+
+Roboto Flex is under the SIL Open Font License (`dist/fonts/RobotoFlex-OFL.txt`).
+
+## Building and publishing (maintainers)
+
+`pnpm build` writes `dist/` and this README (from `docs/quickstart.md` and `README.api.md`): the browser IIFE with the
+engine, `watch.css` and the device profiles inlined, the fonts, `node.mjs` and `cli.mjs` (the app's validator and link
+encoder, bundled). `pnpm pack`, then publish the tarball with `npm publish <tgz> --access public` (pnpm's publish has
+no web two-factor flow). Major versions follow the format: 0.x while `schemaVersion` 2 settles.

package/README.md

@@ -1,48 +1,120 @@
 # @quickwatch/preview
 
-QuickWatch's watch preview as one script: `watch.json` + `data.json` in, the live Wear OS preview out, drawn by the
-same engine as the QuickWatch site and the watch's own rules (the bundle the watch gets, a device profile, the theme).
-Made for pages QuickWatch does not serve, such as a chat assistant's inline widget. Sources show their sample data;
-taps and actions are simulated; nothing is fetched except the two font files next to the script.
+QuickWatch's watch preview for chats and pages, and its validator for Node.
 
-The format: https://quickwatch.app/llms.txt (the agent guide, the JSON Schema and examples).
+## Quick start for AI assistants
 
-The quickest way, a standard layout for a chat widget (the watch, a button per screen, any problems, and an
-"Open in QuickWatch" button that opens the app on quickwatch.app to keep it and send it to the watch):
+QuickWatch puts a small app on a Wear OS watch. The app is two JSON documents: `watch.json` (the app) and `data.json`
+(sample or mock data). You don't need the QuickWatch connector.
+
+### How do I show a preview in the chat?
+
+Put this HTML in an inline HTML widget or artifact (in Claude: the `show_widget` tool). It works as it is. For your
+app, replace the two JSON blocks and change nothing else:
 
 ```html
-<div id="app"></div>
-<script src="https://cdn.jsdelivr.net/npm/@quickwatch/preview@0/dist/quickwatch-preview.min.js"></script>
+<script type="application/json" data-qw-watch>
+{
+  "schemaVersion": 2,
+  "sources": { "weather": { "type": "http", "url": "https://api.example.com/weather", "refresh": { "poll": "15m" } } },
+  "experiences": {
+    "weather": {
+      "title": "Weather",
+      "icon": "cloud",
+      "pages": { "now": { "title": "Stockholm", "root": { "type": "text", "value": "{{ weather.temp | round }}°" } } },
+      "tile": { "template": "text", "title": "Weather", "text": "{{ weather.temp | round }}°" },
+      "complication": { "kind": "shortText", "text": "{{ weather.temp | round }}°" }
+    }
+  }
+}
+</script>
+<script type="application/json" data-qw-data>
+{ "weather": { "temp": 14.2 } }
+</script>
 <script>
-  QuickWatch.widget(document.getElementById('app'), watchJson, dataJson);
+  var s = document.createElement("script");
+  s.src = "https://cdn.jsdelivr.net/npm/@quickwatch/preview@0.3.0/dist/quickwatch-preview.min.js";
+  s.onerror = function () { document.body.append("Could not load the QuickWatch preview."); };
+  document.head.appendChild(s);
 </script>
 ```
 
-`QuickWatch.link(watchJson, dataJson)` resolves to the same Open in QuickWatch link, to put in a reply.
-`QuickWatch.widget` takes `render`'s options plus `origin` (default `https://quickwatch.app`) and `title`.
+It shows the real watch, drawn by QuickWatch's own renderer, with a button for each screen (pages, tile, complication),
+any problems in red, and an **Open in QuickWatch** button. The user presses it to keep the app and send it to their
+watch. Don't draw the watch by hand.
 
-Just the watch, for your own layout:
+### What goes in watch.json?
 
-```html
-<div id="watch"></div>
-<script src="https://cdn.jsdelivr.net/npm/@quickwatch/preview@0/dist/quickwatch-preview.min.js"></script>
-<script>
-  const preview = QuickWatch.render(document.getElementById('watch'), watchJson, dataJson, { size: 300 });
-  // preview.surfaces → [{ key: 'page:main', label, kind }, …, { key: 'tile' }, { key: 'complication' }]
-  // preview.show('tile'); preview.show('overview');  preview.update(newWatchJson, newDataJson);  preview.errors
-</script>
-```
+- `schemaVersion` is `2`.
+- `sources`: where data comes from, by name. `"type": "http"` with a `url` (QuickWatch fetches it; add
+  `"mode": "direct"` to have the watch fetch it), or `"type": "feed"` (your server pushes values).
+- `experiences`: the apps on the watch. Each needs `title`, `pages` and `tile`. `complication` is optional.
+- A page has a `title` and a `root` component: `text`, `stat`, `list`, `status`, `progress`, `countdown`, `button`,
+  `toggle`, `icon`, or `stack` to lay out several.
+- Text reads data with `{{ source.field }}`, for example `{{ weather.temp | round }}`.
+- `data.json` has sample data for every source, by name. Put mock data there.
+- Ids are lowercase letters, digits and `-`. Unknown properties are errors. API keys never go in the JSON.
+
+### How do I check it?
+
+Run `npx @quickwatch/preview check watch.json data.json`. It validates exactly as QuickWatch does, prints the
+problems with their JSON paths, and prints the Open in QuickWatch link. The widget also shows problems in red.
+
+### How does the user keep it?
+
+With the widget's **Open in QuickWatch** button. To put the link in your reply too, take it from the check above. The
+format is `https://quickwatch.app/new#c=<payload>`, where the payload is base64url of deflate-raw of the JSON
+`{ "v": 1, "config": <watch.json>, "data": <data.json> }`. Encoders:
+https://quickwatch.app/docs/agent-guide.md#the-open-in-quickwatch-link
+
+### More
+
+- Assistant guide: https://quickwatch.app/llms.txt
+- Full format, worked examples and errors: https://quickwatch.app/docs/agent-guide.md
+- JSON Schema: https://quickwatch.app/schema/quickwatch.schema.json
+- Every component, tile template, complication kind and icon: https://quickwatch.app/schema/capabilities.json
+- Connector, to build straight to the watch: https://quickwatch.app/mcp
+
+## The package
+
+`@quickwatch/preview` is QuickWatch's watch preview as one script, plus QuickWatch's validator for Node.
+
+In a page (the script from jsDelivr, `window.QuickWatch`):
+
+- **Auto-mount** (above): `<script type="application/json" data-qw-watch>` and `data-qw-data` blocks are drawn as the
+  widget whenever the script finishes loading. Pair several by value (`data-qw-watch="a"` with `data-qw-data="a"`),
+  put the widget in a `[data-qw-mount]` element, and set the site with `data-qw-origin`.
+- `QuickWatch.widget(element, watch, data, options)`: the same widget, into an element. Options: `title`, `origin`
+  (default `https://quickwatch.app`) and those of `render`.
+- `QuickWatch.render(element, watch, data, options)`: just the watch. Options: `surface` (`overview`, `tile`,
+  `complication`, `page:<id>`), `experience`, `device` (`QuickWatch.devices`), `theme` (`auto` or
+  `QuickWatch.themes`), `data` (`sample`, `loading`, `error`, `empty`, `stale`), `ambient`, `size` (CSS px across the
+  face), `frame`, `onUpdate`, `onError`. Returns `{ surfaces, surface, show(key), update(watch, data), errors,
+  destroy() }`.
+- `await QuickWatch.link(watch, data)`: the Open in QuickWatch link.
+
+`watch` and `data` are objects or JSON text (comments and trailing commas allowed). Nothing is fetched except the two
+font files next to the script; sources show their sample data and actions are simulated.
+
+The widget and the watch draw inside shadow roots (with `all: initial` on the host), so the page's styles, such as a
+chat panel's rules for buttons, links and text, cannot change them; only the two `@font-face` rules go into the page's
+`<head>`. The widget's light or dark look follows the background it sits on (`appearance: 'light' | 'dark'` to
+choose).
+
+In Node (`import { check, link } from '@quickwatch/preview'`) and the shell:
+
+- `npx @quickwatch/preview check watch.json data.json [--origin <url>] [--json]`: validates with QuickWatch's own
+  validator, prints the problems (JSON path, rule, line and column) and the Open in QuickWatch link. Exit code 1 when
+  there are errors.
+- `await check(watch, data)`: `{ issues, errors, warnings, link }`. `await link(watch, data)`: the link.
 
-`watchJson` and `dataJson` are objects or JSON text (comments and trailing commas allowed). Options: `experience`
-(default the first), `surface` (`overview`, `tile`, `complication`, `page:<id>`), `device` (`QuickWatch.devices`,
-default `galaxy-watch`), `theme` (`auto` or one of `QuickWatch.themes`), `data` (`sample`, `loading`, `error`,
-`empty`, `stale`), `ambient`, `size` (CSS px across the face), `frame` (draw the case, default true) and `onUpdate`.
+Pin an exact version (`@quickwatch/preview@0.3.0`) to skip jsDelivr's redirect from `@0`.
 
 Roboto Flex is under the SIL Open Font License (`dist/fonts/RobotoFlex-OFL.txt`).
 
 ## Building and publishing (maintainers)
 
-`pnpm build` writes `dist/`: the IIFE (`window.QuickWatch`) with the engine, `watch.css` and the device profiles
-inlined, and the fonts. It also bundles the app's bundle builder (`app/src/lib/drafts/bundle.ts`), so the preview
-builds exactly what the watch receives. `pnpm publish --access public` builds first (`prepublishOnly`). The major
-version follows the format: 0.x while `schemaVersion` 2 settles.
+`pnpm build` writes `dist/` and this README (from `docs/quickstart.md` and `README.api.md`): the browser IIFE with the
+engine, `watch.css` and the device profiles inlined, the fonts, `node.mjs` and `cli.mjs` (the app's validator and link
+encoder, bundled). `pnpm pack`, then publish the tarball with `npm publish <tgz> --access public` (pnpm's publish has
+no web two-factor flow). Major versions follow the format: 0.x while `schemaVersion` 2 settles.