create-opentray 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-opentray",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Turn any start command that serves HTTP locally into an OpenTray-hosted desktop app.",
   "type": "module",
   "license": "MIT",
@@ -26,13 +26,10 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "sharp": "^0.33.5",
     "yargs": "^18.0.0",
-    "@create-opentray/core": "0.1.2",
-    "@opentray/packaging": "0.21.0",
-    "@opentray/spec": "0.21.0",
-    "@opentray/vite-plugin": "0.21.0",
-    "@create-opentray/cli": "0.1.2"
+    "@opentray/packaging": "0.22.0",
+    "@opentray/spec": "0.22.0",
+    "@opentray/vite-plugin": "0.22.0"
   },
   "optionalDependencies": {
     "@lydell/node-pty": "^1.1.0"
@@ -42,7 +39,9 @@
     "ghostty-web": "^0.4.0",
     "tsdown": "^0.22.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.7",
+    "@create-opentray/core": "0.1.4",
+    "@create-opentray/cli": "0.1.4"
   },
   "engines": {
     "node": ">=20"

package/skill/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: create-opentray
-description: create-opentray guide for turning any HTTP-serving start command into an OpenTray-hosted desktop application — WebUI wizard, non-interactive CLI creation, the v1 create-opentray.json configuration authority, the fixed ~/.opentray/create registry, application lifecycle (edit, copy, export, uninstall), icon handling including pixel-art smoothing, developer mode, and platform limitations. Use when scaffolding or managing applications created by create-opentray.
+description: create-opentray guide for turning any HTTP-serving start command — or any http(s) URL — into an OpenTray-hosted desktop application — WebUI wizard, non-interactive CLI creation, the v1 create-opentray.json configuration authority, the fixed ~/.opentray/create registry, application lifecycle (edit, copy, export, uninstall), icon handling including pixel-art smoothing, developer mode, and platform limitations. Use when scaffolding or managing applications created by create-opentray.
 ---
 
 # create-opentray
 
 ## Overview
 
-`create-opentray` packages a start command that serves HTTP locally into an
-OpenTray-hosted desktop application: a real tray icon, a webview window, and a
-supervised child process. This skill explains how it works, how to drive it
-non-interactively, and how to manage created applications.
+`create-opentray` packages a start command that serves HTTP locally — or a
+plain http(s) URL — into an OpenTray-hosted desktop application: a real tray
+icon, a webview window, and (for command apps) a supervised child process.
+This skill explains how it works, how to drive it non-interactively, and how
+to manage created applications.
 
 Three adapter surfaces share one Core:
 
@@ -18,8 +19,9 @@ Three adapter surfaces share one Core:
    WebUI wizard. It can run your command once, discover the HTTP ports it
    owns, and suggest a name/icon from the served page.
 2. `create-opentray create …` — fully non-interactive creation. No browser,
-   no prompts, no sniffing: identity, icons, and the command vector are all
-   explicit.
+   no prompts, no sniffing: identity, icons, and the command vector (or the
+   `--url` address) are all explicit; under `--url` the identity derives
+   from the address offline.
 3. `create-opentray app …` — manage registered applications: list, edit,
    copy, export, uninstall.
 
@@ -29,10 +31,12 @@ OpenTray is a desktop status platform: your application calls `createTray()`
 and owns its own foreground/background lifetime. A created application is a
 small generated project whose entry (`main.mjs`):
 
-- spawns your recorded start command as a supervised child,
-- discovers the command's owned HTTP listening ports at runtime,
-- hosts each verified port in an application-mode webview window, and
-- owns the tray session with a Quit menu item.
+- command app: spawns your recorded start command as a supervised child,
+  discovers the command's owned HTTP listening ports at runtime, and hosts
+  each verified port in an application-mode webview window;
+- URL app (`--url`): opens exactly one application-mode webview window at
+  the frozen address and supervises nothing;
+- both own the tray session with a Quit menu item.
 
 The generated project depends only on published packages (`opentray`,
 `@opentray/ext-webview`) — never on the create-opentray tool itself.
@@ -49,12 +53,13 @@ Every registered application has exactly one editable desired-state document:
   tray-icon.<ext>
 ```
 
-`create-opentray.json` records app identity and name, the exact command
-vector (executable, args, cwd, env overlay), package-manager choice, icon
-resource references with content hashes and provenance, icon-rendering
-options (including `imageSmoothingEnabled`), window options, and
-`developerMode`. Generated files are derived output — editing them is
-overwritten on the next apply; edit the JSON instead.
+`create-opentray.json` records app identity and name, exactly ONE source
+(the command vector — executable, args, cwd, env overlay — or a `url`
+address), package-manager choice, icon resource references with content
+hashes and provenance, icon-rendering options (including
+`imageSmoothingEnabled`), window options, and `developerMode`. Generated
+files are derived output — editing them is overwritten on the next apply;
+edit the JSON instead.
 
 Key rules:
 
@@ -81,6 +86,30 @@ npx create-opentray create \
 
 - `--arg` is repeatable and each value is ONE exact argv element — never a
   shell string. Metacharacters like `&&` stay literal.
+- `--url <address>` packages an http(s) URL directly (no command):
+
+  ```sh
+  npx create-opentray create --url https://example.com/app
+  ```
+
+  Identity derives offline from the address (`app.com.example` / `App`);
+  override with `--app-id`/`--app-name`. It is mutually exclusive with
+  `--exec`/`--arg`/`--cwd`/`--env`. Because the address is known up front,
+  creation scrapes the page once and adopts its `<title>` and best favicon
+  as DEFAULTS (explicit flags win; failures fall back silently; `--no-scrape`
+  skips the fetch). `app edit <id> --url <new-address>` changes it later;
+  export emits `--url`.
+- URL app window behavior (all persisted in v1 config, export round-trips):
+  `--toolbar` wraps the address in the shared address-bar page (back/forward/
+  reload buttons + ⌘/Ctrl+←→, ⌘/Ctrl+[] , ⌘/Ctrl+R, F5, ⌘/Ctrl+L shortcuts
+  while the wrapper has focus). Embedding-hostile targets (X-Frame-Options /
+  CSP frame-ancestors refusing third-party iframes) are detected during the
+  creation scrape and degrade to the direct window with a notice — e.g.
+  news.ycombinator.com sends `X-Frame-Options: DENY`, so HN always runs
+  direct;
+  the tray menu always offers Reload; the window title follows the document
+  by default (`--no-title-follow` opts out) and favicon following is opt-in
+  (`--icon-follow`).
 - Icon sources may be local files, `http(s)` URLs, or `data:` URLs. The CLI
   never scrapes names or favicons — everything is explicit.
 - `--dry-run` prints the Core plan (effects, warnings, blocks) without

package/skill/references/cli-reference.md

@@ -11,13 +11,15 @@ loopback port), `--no-open` (do not launch the default browser).
 
 ## `create-opentray create`
 
-Non-interactive creation. Options:
+Non-interactive creation. A v1 application carries exactly one source: the
+command flags (`--exec` family) OR `--url`. Options:
 
 | Option | Meaning |
 | ------ | ------- |
 | `--config <file>` | base v1 document; explicit flags override named fields only |
-| `--app-id <id>` | immutable reverse-dotted identity (required without `--config`) |
-| `--app-name <name>` | display name (required without `--config`) |
+| `--app-id <id>` | immutable reverse-dotted identity (required without `--config`/`--url`) |
+| `--app-name <name>` | display name (required without `--config`/`--url`) |
+| `--url <address>` | URL source: open this http(s) address directly (no command); scrapes the page for default name/icon unless `--no-scrape`; mutually exclusive with `--exec`/`--arg`/`--cwd`/`--env` |
 | `--exec <executable>` | command executable |
 | `--arg <value>` | one exact argv element (repeatable) |
 | `--cwd <dir>` | command working directory (default: current) |
@@ -31,6 +33,9 @@ Non-interactive creation. Options:
 | `--tray-template` | treat the tray source as a darwin template |
 | `--developer-mode` | admit WebView DevTools (default false) |
 | `--window <WxH>` | window size (default 1200x800) |
+| `--toolbar` | URL apps: host the address-bar wrapper (back/forward/reload + shortcuts) |
+| `--title-follow <bool>` | window title follows document.title (default true; negate with `--no-title-follow`) |
+| `--icon-follow <bool>` | runtime favicon→window-icon following (default off) |
 | `--force` | replace a VERIFIED existing payload |
 | `--stop-running` | stop a verified running instance first |
 | `--skip-install` | write the project without installing |

package/skill/references/how-it-works.md

@@ -1,5 +1,20 @@
 # How create-opentray works
 
+## The two application sources
+
+A v1 application carries exactly ONE source:
+
+- **Command** — `--exec/--arg/--cwd/--env`: create-opentray supervises a local
+  start command and hosts the HTTP services it owns.
+- **URL** — `--url <http(s) address>`: no command at all. The generated app
+  opens one window directly at the frozen address. The address is known up
+  front (unlike a command that must run first), so creation scrapes the page
+  once and adopts its `<title>` and best favicon as DEFAULTS — explicit flags
+  win, failures fall back silently to the address-derived name and a glyph
+  icon, and `--no-scrape` skips the fetch. appId always derives from the
+  address text, never from page content. URL apps carry no PTY, no
+  terminal/address-bar shell, and no env overlay.
+
 ## The creation pipeline
 
 1. **Desired state** — CLI flags or the WebUI form compile into one v1
@@ -15,6 +30,8 @@
 
 ## What the generated app does at runtime
 
+Command apps:
+
 - Reads the frozen command vector from its derived config and spawns the
   command with an absolute, PATH-independent executable.
 - Continuously monitors the command's OWNED listening ports (ownership is
@@ -25,6 +42,19 @@
 - Publishes a tray with Quit; optional startup-terminal and address-bar
   shells when configured.
 
+URL apps:
+
+- Publish the tray (Show/Reload/Quit) and one application-mode webview
+  window at the frozen URL. The title follows the page document by default
+  (one-way); runtime favicon→icon following is opt-in (`--icon-follow`).
+- Toolbar mode (`--toolbar`) wraps the address in the shared address-bar
+  page: back/forward/reload buttons, an address input, and the ⌘/Ctrl
+  navigation shortcuts while the wrapper has focus (keystrokes inside a
+  cross-origin embedded page are not observable by the wrapper; the tray
+  Reload item always works). Sites that forbid embedding cannot be wrapped.
+- Supervise nothing: no child process, no port monitor; Quit destroys the
+  window and tray session and exits.
+
 ## Force and ownership
 
 `--force` is not "overwrite anything": it may only replace a payload whose