hopple 0.0.0 → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,40 @@
+MIT License
+
+Copyright (c) 2026 The Hopple authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+The files `hopple create` writes into a new project are not under the license
+above. They are under the BSD Zero Clause License (0BSD), so a game made from
+them owes nothing to anyone:
+
+Copyright (c) 2026 The Hopple authors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# hopple: the command line
+
+The command-line tool for game developers:
+
+- `hopple create` starts a new game with the recommended setup (optional).
+- `hopple dev` runs a built game in the **dev shell**, a host made for
+  testing, which runs it with the same code as the real clients.
+- `hopple check` says whether a game can be published, and `hopple publish`
+  uploads it to a Hopple server.
+- `hopple list`, `login`, `logout` and `whoami` manage what you've published
+  and who you publish as.
+
+It is a dev dependency of the game (`npm install --save-dev hopple`, which
+`hopple create` sets up), run with `npx hopple`. It is one compiled file with
+no dependencies, and needs Node 22.18 or later.
+
+`hopple` is not a bundler. It takes a game that is already built, by
+whatever tool the game uses.
+
+## The project's config
+
+`dev`, `check` and `publish` work on a **project**: a directory with a hopple
+config in it. They find it in the current directory, or the nearest one above
+it (like `tsconfig.json`). The config says everything they need to know:
+
+```ts
+// hopple.config.ts
+import type { HoppleConfig } from '@hopple/sdk';
+
+export default {
+  build: 'npm run build',
+  page: 'dist/index.html',
+  manifest: {
+    schema: 1,
+    id: 'my-game',
+    version: '0.1.0',
+    title: 'My Game',
+    orientation: 'portrait',
+    sdk: '^0.1.0',
+    audio: null,
+  },
+} satisfies HoppleConfig;
+```
+
+- **`build`** (optional) is the command that builds the game. It runs first, in
+  the config's directory, and a failed build stops the command. So
+  `npx hopple publish` can't upload a stale build. `--no-build` skips it.
+- **`page`** is the built HTML file, relative to the config. It is the one file
+  that is played in the dev shell and published, so it must contain the whole
+  game.
+- **`manifest`** is what the game is: its id, title, description, and what it
+  declares. See [the manifest's reference](https://docs.hopple.app/manifest.md).
+
+Only the page and the manifest are uploaded; `build` and `page` never leave
+your machine.
+
+The config can be `hopple.config.ts`, `hopple.config.js` (both default-export
+it) or `hopple.config.json` (which is it). A TypeScript config needs no build
+of its own: Node runs it. Any other key is an error, so a misspelt `build`
+can't be silently skipped, and two configs in one directory are an error too.
+
+A JSON config can start with
+`"$schema": "./node_modules/@hopple/sdk/config.schema.json"` for completion
+and errors in an editor, the manifest's included.
+
+## Commands
+
+```
+hopple create  <dir>
+hopple dev     [project] [--port <n>] [--no-build]
+hopple check   [project] [--no-build]
+hopple publish [project] [--server <url>] [--no-build]
+hopple list    [--server <url>]
+hopple login   [--server <url>]
+hopple logout  [--server <url>]
+hopple whoami  [--server <url>]
+hopple --version
+```
+
+`[project]` is a project's directory (or a directory inside it), or its config
+file. Left out, it is the current directory.
+
+The server is taken from `--server`, then `$HOPPLE_SERVER`, then
+`https://hopple.app`. It is named by its site; the CLI finds the API under
+`/api` on it.
+
+### `hopple create`
+
+```bash
+npx hopple create my-game
+cd my-game && npm install
+npx hopple dev        # build, then play it in the dev shell
+npm run watch          # in another terminal: rebuild on every change, then reload the shell
+npx hopple publish    # build, check, then publish
+```
+
+Writes a new project into `<dir>`, which must be new or empty. The directory's
+name becomes the game's id (lowercase letters, digits and hyphens). It is the
+recommended setup, not a requirement:
+
+- **Vite** builds it, with `vite-plugin-singlefile` inlining every script,
+  style and imported asset into `dist/index.html`.
+- **`hopple.config.ts`** builds with `npm run build` (typecheck with `tsc`,
+  then bundle), names `dist/index.html` as the page, and holds the manifest.
+  Being TypeScript, a mistake in the manifest is a type error.
+- **There is no `publish` script**: `npm publish` would run it, then upload the
+  project to the npm registry. The project is also `"private": true`.
+- `src/game.ts` is a small working game (a ball you keep in the air) that uses
+  the SDK the way every game should: `init`, the loop, layout, input and pause.
+
+A game built any other way (another bundler, or a hand-written HTML file) is
+played and published with the same commands, once it has a config.
+
+### `hopple dev`
+
+```bash
+npx hopple dev                          # this project's game, built: http://localhost:5173
+npx hopple dev path/to/project --port 8080
+```
+
+The dev server serves:
+
+- `/`: the dev shell.
+- `/game/`: the config's `page`, and `/game/…` the other files in its
+  directory, with CORS enabled and caching disabled. Nothing outside that
+  directory is served.
+
+A valid manifest is shown in the shell. An invalid or missing one is reported
+in the terminal and on the page, naming the bad fields, and the game still
+runs. The config is read again every time the shell page loads, so **an edited
+manifest shows up on reload**, with no restart. So does a rebuilt game.
+
+It plays a build that loads files from beside its page (a separate script, a
+stylesheet, images), but says in the terminal that it can't be published like
+that.
+
+**With no project to be found**, the shell starts empty and waits for a URL
+like `/?server=<server url>&game=<owner>/<name>@<version>`. The admin pages'
+"Dev shell" button opens exactly that, so you can run any uploaded game (yours
+or someone else's) in the dev shell. The shell downloads the game and its
+manifest from that server's feed and runs it exactly as it would a local build.
+
+### `hopple check`
+
+```bash
+npx hopple check                  # this project's game, built
+npx hopple check --no-build       # as it was last built
+```
+
+Everything `publish` checks before it uploads, without uploading:
+
+1. The manifest validates.
+2. The **page** exists, and loads nothing from outside itself: no
+   `<script src>`, stylesheet `<link>`, `<img>` or CSS `url()` that isn't a
+   `data:` URL. Only that one file is published, so it must contain the whole
+   game, with every script and asset inlined. (Files the game's code fetches
+   can't be seen this way; they fail the same way.)
+
+It exits with 1 and says what is wrong, or prints the game's id, version and
+size.
+
+### `hopple publish`
+
+```bash
+npx hopple publish                # this project's game, built
+npx hopple publish path/to/project
+```
+
+1. Makes every check `hopple check` makes, so mistakes are caught before
+   anything is uploaded.
+2. Uploads the manifest and the page, and publishes them as
+   `<your username>/<manifest id>`, as a new version. The game is listed with
+   the manifest's `title` and `description`: to change them, change the
+   manifest.
+3. Prints the version's address, whether it is live, and a link that opens that
+   exact version.
+
+If you are a trusted user or an admin, the version goes live immediately.
+Otherwise it waits for an admin to review it, and the previous live version
+(if any) stays in the feed meanwhile.
+
+### `hopple login`, `logout`, `whoami`, `list`
+
+- The first command that talks to a server starts an **anonymous session**,
+  so you can publish without an account.
+- `hopple login` signs that same session in. It prints a link and a short
+  code, and waits: open the link in a browser where you are signed in to the
+  site (or sign in there, any way the site offers), check that the page shows
+  the same code, and approve. Nothing is typed in the terminal, and the link
+  can be opened on another machine. It is good for ten minutes.
+  Anything you published anonymously from this machine moves into your account.
+- `hopple whoami` shows who you are on that server and how you signed in.
+- `hopple logout` ends the session and forgets it.
+- `hopple list` shows each game you've published, its live version, its
+  newest version if different (and whether it is waiting for review), and a
+  link to each.
+
+Sessions are stored per server in `~/.config/hopple/sessions.json` (or under
+`$XDG_CONFIG_HOME`, or `$HOPPLE_CONFIG_DIR` if set), readable only by you.
+The file contains your session tokens, so treat it like a password.
+
+Every request names the CLI and its version (`User-Agent: hopple-cli/<version>`).
+The server uses that to count games published and terminals signed in from
+the CLI, under your Hopple player in our usage analytics. Nothing else is
+collected, and nothing is collected on your machine. Set `DO_NOT_TRACK=1` to
+leave your publishes and sign-ins out of those counts.
+
+## The dev shell
+
+The dev shell runs the game the way real hosts do (same sandbox, same bridge),
+but surrounds it with controls for testing. Its panel (opened from the rail's
+handle or the corner button) has:
+
+- **Device**: the frame's shape (portrait phone, landscape phone, or the whole
+  browser window), where the host's buttons go, and a fake notch.
+- **Lifecycle**: switch the game between `active`, `passive` and `hidden`; the
+  log shows the orders each one sends (sound, loop, resources). Ping it.
+- **Info**: device tier, locale, whether the player is returning, and "be a new
+  player". Each of these **restarts the game**, because info is only sent once,
+  at the start.
+- **Manifest**: what the game declares.
+- **The log**: every analytics event, every refusal, every save read, write and
+  clear (with sizes), every share link, and every error the game threw, with
+  its stack. An error also shows over the game until it is read, and is
+  printed in the terminal `hopple dev` runs in: once with its stack, then again
+  only when it has been thrown 10, 100, 1000… times, and whole again after a
+  restart.
+
+Switches that make the host misbehave on purpose, so you can see your game
+cope:
+
+- Reserve the host's buttons even though the game said `draw-under`.
+- A host with no save store, a full one, or one that takes 2 seconds to reply.
+- A host with no scores, no achievements, no panel, no input settings, no
+  audio settings, or that never asks the game to pause. These restart the game,
+  since what a host offers is settled at the start.
+- Analytics rate limits like a real host's: 10 events a second, 15 in 15
+  seconds, 30 a minute.
+
+What each feature does in the shell:
+
+| Feature | In the dev shell |
+|---|---|
+| Save | Stored in the browser's `localStorage`. The panel shows what is stored, its size and age, and can delete it. |
+| Score | A made-up leaderboard, so you can see how a rank looks before any real players exist. You can set the range. Your submitted scores join it. Reloading generates a new one. |
+| Achievements | Kept in memory for one player. *Reset* clears them **without** restarting the game (the running game keeps what it was told, just as in a real client). |
+| Share | Every link (the game's, or the rail's Share button) gets a record kept in the browser's `localStorage`: where it came from, and the game's `data` and `meta`. The record is written to the log, the link is copied to the clipboard, and the game is told `copied`. Opening the link in the same browser restarts the game with that data. *Open without the link* drops it. |
+| Panel | The same panel as a real host's, with the game's pages in it. The game can ask for one; opening the panel yourself, on the game's pages or on others, shows how the game reacts to a panel it didn't ask for. |
+| Input | The key-binding page, and a switch for which input device the player is using. |
+| Sound | Mute, master volume and a slider per declared channel, in the panel, on the game's page. The log says whether the game answered with the mix it was asked for. |
+| Pause | A button in the corner, shown only when the game says it can pause. |
+
+## License
+
+MIT; see `LICENSE`. The files `hopple create` writes into a new
+project are under 0BSD instead, so a game made from them owes nothing to
+anyone. The license covers the code, not the Hopple name or logo.

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,138 @@
+The hopple CLI includes the following packages, under the licenses below.
+
+--------------------------------------------------------------------------------
+
+@stylexjs/stylex 0.15.4 (MIT)
+
+Licensed under MIT. The package ships no license text.
+
+--------------------------------------------------------------------------------
+
+react-dom 19.2.3 (MIT)
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+react-strict-dom 0.0.55 (MIT)
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+react 19.2.3 (MIT)
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+scheduler 0.27.0 (MIT)
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+uqr 0.1.3 (MIT)
+
+MIT License
+
+Copyright (c) Project Nayuki
+Copyright (c) 2023 Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.