hyperdecks 0.1.8 → 0.1.10

package/README.md

@@ -3,17 +3,18 @@
 Friendly npm package name for the Hypersocial Decks CLI.
 
 ```bash
-pnpm dlx hyperdecks whoami
-pnpm dlx hyperdecks deck list
-pnpm dlx hyperdecks activity --limit 20
-pnpm dlx hyperdecks import ./claude-design-export.zip --slug acme-pitch
-pnpm dlx hyperdecks skills install
+npx hyperdecks whoami
+npx hyperdecks deck list
+npx hyperdecks activity --limit 20
+npx hyperdecks import ./claude-design-export.zip --slug acme-pitch
+npx hyperdecks skills install
 ```
 
-Global install:
+Global install (no repository checkout needed):
 
 ```bash
-pnpm add -g hyperdecks
+npm install -g hyperdecks
+hyperdecks login
 hyperdecks whoami
 decks whoami
 ```
@@ -61,3 +62,49 @@ hyperdecks skills install
 This delegates to `npx skills add`, installing the bundled skill for Codex and
 Claude Code by default. Use `--agent <ids>` for specific agents or
 `--all-agents` for every supported agent.
+
+## QA links and muted telemetry (0.1.10)
+
+```bash
+hyperdecks share new acme-pitch "QA" --qa
+hyperdecks share new isolated-test-deck "Telemetry test" --no-notify
+hyperdecks share mute <token>
+hyperdecks share unmute <token>
+hyperdecks deck stats acme-pitch --json
+```
+
+QA links exercise the full runtime without tracking or notifications and cannot
+be unmuted. A normal muted link on an isolated deck can verify telemetry. Human
+and JSON stats distinguish narration started/finished from unknown legacy
+playback. Production is the default for login, import, share and statistics;
+`--dev` with an explicit backend is only for implementation testing.
+
+The 0.1.10 release is prepared here; npm publication remains a separate
+coordinated step after backend/frontend rollout. Both `hyperdecks` and `decks`
+resolve to the same implementation.
+
+Existing published 0.1.9 supports production login, import and ordinary share
+creation; publishing 0.1.10 is not required for those flows.
+
+## Animated email previews (prepared 0.1.10; publication pending)
+
+This command is implemented in the prepared CLI source. npm publication, deployment of the owner-only `previews:get` Convex query, and upgrading a global CLI are coordinated release steps still pending. Local-file export needs no login or backend deployment. Both `hyperdecks` and `decks` accept the same command; the canonical package is `@hypersocial/decks-cli`.
+
+```sh
+hyperdecks preview setup
+hyperdecks preview create --file ./presentation/index.html --out ./preview-local --json
+hyperdecks share list my-deck --json
+hyperdecks preview create my-deck --share EXISTING_TOKEN --out ./preview-email --upload --json
+```
+
+Generate locally, select an existing same-deck recipient share, then explicitly upload into a **new** output directory. The command never creates or visits a share. Upload requires an owned deck slug; `--file` with `--upload` or `--share` is rejected. Disabled, expired, exhausted and mismatched shares fail before upload. QA shares are supported intentionally: their click-through remains untracked and muted, so use a regular recipient share for measured outreach.
+
+Capture defaults to the initial slide, 4 seconds, 600px width and 10 fps, with a play/watch badge on GIF, PNG and silent MP4. `--duration` accepts 1–10 seconds, `--width` 240–1200 pixels (odd widths round up for MP4), `--delay` 0–10000 milliseconds (default 1000), and `--label "Watch · 2:41"` supplies an explicit label; no whole-deck narration duration is inferred. Aspect comes from `--aspect-ratio W:H`, `<meta name="preview-aspect-ratio" content="16:9">`, or the first slide/canvas bounds; otherwise 16:9. Output height rounds to an even pixel. Fonts get up to 5 seconds to settle. Inspect readiness warnings/poster for slow modules or media and increase the bounded delay if needed.
+
+`--json` prints one result on stdout; errors/progress use stderr and failures exit nonzero. `manifest.json` records source, status, absolute artifact paths, MIME types, bytes, dimensions, clip durations/fps, share URL, warnings and each completed upload. Files larger than 5 MiB warn: reduce duration/width for email. On upload failure local artifacts survive; inspect the manifest's URLs and `upload` records (an uploaded storage blob can exist even if saving its asset failed). Retry in a fresh directory; never overwrite an image already used in an email.
+
+Only successful explicit uploads produce `email.html` and `email.sendable: true`, with the GIF wrapped in the exact recipient link. Use that HTML/GIF in your draft manually. Some email clients show only the first GIF frame: the PNG poster and the visible watch badge provide a static fallback. MP4 is for other channels; email video support varies. Local exports provide files to insert manually and a separate share URL when selected, with no claim of sendable remote-image HTML. Static image downloads do not open the deck, start narration, record engagement, or notify the owner.
+
+Playwright and the platform FFmpeg executable are declared dependencies loaded only for preview capture; normal login/import/stats do not need capture prerequisites. `preview setup` installs the matching Chromium with no personal profile. On Linux, install Playwright's system libraries using `npx playwright@1.64.1 install-deps chromium` (may need administrator access), then run setup. FFmpeg comes from `@ffmpeg-installer/ffmpeg`, never a global/Homebrew executable. npm installs must include optional dependencies and allow install scripts; pnpm users must approve their `@ffmpeg-installer/<platform>` chmod script. Reinstall with `npm install -g hyperdecks --include=optional` if it is missing. Unsupported platforms fail with recovery guidance.
+
+The local server exposes only supported static files within the explicit HTML file's directory; dotfiles, traversal and outside symlinks are denied. Keep capture inputs in a dedicated asset directory. Relative modules/fonts/video and external `<base>` URLs are retained. A fresh browser context receives no CLI credentials, cookies, profile or environment secrets. Recipient routes, first-party telemetry, non-GET requests, sockets and unrelated local services are blocked by URL and DNS checks that fail closed on lookup errors. Chromium resolves independently, so DNS rebinding is not fully prevented; use OS/network isolation for untrusted content. Video stays muted; the exporter does not click controls or start narration. Capture is bounded and temporary browser/server/frame files are removed on success/failure. Use only trusted deck content; third-party static resources may be fetched while rendering. HTTP redirects are refused before the browser follows them; use direct final asset URLs if a resource warns or fails to load.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperdecks",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Friendly CLI for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,7 +16,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@hypersocial/decks-cli": "^0.1.8"
+    "@hypersocial/decks-cli": "^0.1.10"
   },
   "publishConfig": {
     "access": "public"