@fabi-play/protocol 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,76 @@
+Fabi Play Kit License
+Version 1.0 (DRAFT, not yet reviewed by a lawyer)
+
+Copyright (c) 2026 Fabi Play. All rights reserved.
+
+This license applies to the Fabi Play Kit: the packages @fabi-play/protocol, @fabi-play/motion,
+@fabi-play/avatars, @fabi-play/sdk and @fabi-play/engine, in source and built form, as published on npm, served
+from https://cdn.fabiplay.app or found in this repository, including their code, type declarations, documentation,
+avatar artwork and other assets (together, the "Kit").
+
+1. Free of charge, for Fabi Play only
+
+   Fabi Play grants you a worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to
+   use, copy, and modify the Kit, and to distribute it as part of a Permitted Work, solely to make, test, run and
+   distribute Permitted Works.
+
+   A "Permitted Work" is a game, tool, or other software made to run on, be published on, or support the
+   development of games for the Fabi Play platform (https://fabiplay.app), including games submitted to Fabi Play
+   and tools used to build, test or preview them.
+
+2. What is not allowed
+
+   You may not, without Fabi Play's prior written permission:
+
+   a. use the Kit, or any part or modified version of it, in software that is not a Permitted Work, including in
+      any other game platform, product or service;
+   b. distribute the Kit, or a modified version of it, on its own or as a library, SDK, engine or framework for
+      others to build with, other than as part of a Permitted Work (installing it from npm or loading it from
+      https://cdn.fabiplay.app is not a distribution by you);
+   c. sell, rent or sublicense the Kit itself;
+   d. remove or alter this license, copyright notices, or the license banners in the built files;
+   e. use the avatars, the mascot "Fabi", or the name, logos or other trademarks of Fabi Play, except as the Kit
+      does when it runs inside a Permitted Work. This license grants no trademark rights;
+   f. use the Kit to circumvent, interfere with or misrepresent the Fabi Play platform, its safety, privacy or
+      parental controls, or its rules for games.
+
+3. Visible, not open source
+
+   The Kit's code is published so that developers can read it, debug with it and build Permitted Works. Being
+   visible does not make it open source; no rights are granted beyond those stated here.
+
+4. Your works
+
+   You keep all rights in your own code and content. This license does not give Fabi Play any rights in your
+   Permitted Works; publishing a game on Fabi Play is governed by Fabi Play's separate developer terms.
+
+5. Feedback
+
+   If you send Fabi Play suggestions or changes for the Kit, Fabi Play may use them without obligation to you.
+
+6. Termination
+
+   This license ends automatically if you break its terms. If you fix the breach within 30 days of becoming aware
+   of it, the license is reinstated, unless Fabi Play has already told you in writing that it is terminated. On
+   termination you must stop using and distributing the Kit. Permitted Works already distributed to end users in
+   compliance with this license may continue to be used by those end users.
+
+7. No warranty
+
+   THE KIT 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 NON-INFRINGEMENT.
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FABI PLAY OR ITS CONTRIBUTORS 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 KIT OR THE USE OR OTHER DEALINGS IN THE KIT.
+
+9. Changes to this license
+
+   Fabi Play may publish new versions of this license. Each version of the Kit is governed by the license version
+   it is distributed with, unless you choose to accept a later version.
+
+10. Contact
+
+   For permissions beyond this license: https://fabiplay.app

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @fabi-play/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The messages between the phone, the screen and the games of [Fabi Play](https://fabiplay.app), with their checks:
+the body landmarks (`P`, `Body`), players, age bands, the game manifest (`fabi-play.json`, `parseManifest`, and its
+JSON Schema), and the parsers every side runs on what it receives.
+
+```sh
+npm install @fabi-play/protocol
+```
+
+```ts
+import { parseManifest, AGE_RANGES, type GameManifest } from '@fabi-play/protocol'
+
+const result = parseManifest(JSON.parse(text))
+if ('errors' in result) console.error(result.errors)
+```
+
+The manifest's JSON Schema: `@fabi-play/protocol/fabi-play.schema.json` (also served next to the SDK on
+https://cdn.fabiplay.app). ESM only, types included, no dependencies. Docs: https://docs.fabiplay.app.
+
+## The game intro
+
+A manifest's optional `intro` (`GameIntro`: 1 to 4 steps, each a sentence over an image or a move) is what Fabi
+says on the TV before calibration; see "Fabi explains your game" in the
+[`@fabi-play/sdk` README](https://www.npmjs.com/package/@fabi-play/sdk). `parseManifest` reports what is wrong with
+it; `parseIntro` gives the intro or null (the TV skips a bad one, unknown fields included), `introText` the
+sentence for a locale and age.
+
+- **Sentences**: up to 90 characters per language, counted as Unicode code points of the NFC form (an emoji is
+  one); no white space at either end; no control characters, lone surrogates or bidirectional controls
+  (U+202A–U+202E, U+2066–U+2069). The JSON Schema says the same, except lone surrogates and the NFC count, which
+  portable JSON Schema regexes can't express: `parseManifest` is the reference.
+- **Paths** (`entry`, a step's `image`): relative to the game's address, no scheme, no leading `/`, no empty, `.` or
+  `..` segments, up to 200 characters; segments of ASCII letters, digits, `_` and `-` (dots inside, not first);
+  extensions in lowercase: `.html` for `entry`, `.jpg` or `.png` for images (`intro/track.jpg`, not
+  `intro/Track.PNG`). No WebP: old TV browsers (WebKit-based Tizen 2.x, webOS 1–2) may not decode it. JPG (quality
+  about 80) for screenshots, PNG only for flat art.
+- **Voice clips**: a sentence's clip is at `voiceUrl(base, voiceKeySync(text, locale))` (`voiceKey` is the same as
+  a promise). The key is the first 32 lowercase hex characters of SHA-256 of the UTF-8 bytes of
+  `` `${FABI_VOICE}\n${locale}\n${t}` `` (`FABI_VOICE` is `fabi-v1`), where `t` is the text in Unicode NFC with
+  JavaScript's `trim()` applied; a valid sentence has no white space around it, so for a generator in any language
+  `t` is just the NFC text. So `voiceKeySync('Salta!', 'it')` is `cbd16ba39816bdc5afd34a3e84082331` and its clip
+  `https://cdn.fabiplay.app/voice/fabi-v1/cbd16ba39816bdc5afd34a3e84082331.mp3`. The SHA-256 is plain JavaScript,
+  synchronous: no `crypto.subtle`, so it works on TV pages served over http, old TV browsers and Node 18 (the
+  package's `engines`).
+- **The phone's buttons**: during the intro the phone sends `{ type: 'intro', action }`, with action `next`,
+  `repeat`, `skip`, or `replay` (from the pause menu: the explanation again); the screen tells it what Fabi is
+  saying with `{ type: 'intro', step, steps, text, voice }`. Its `phase` message carries `intro: true` when the
+  game has an intro: only then does the phone offer `replay`.
+
+## Poses on the wire
+
+The phone streams `{ type: 'pose', t, bodies }` about 30 times a second over an unordered, no-retransmit data
+channel. A screen that lists `POSE_CODEC_VERSION` in its welcome (`binaryPose: [1]`, see `acceptsBinaryPose`) gets
+them in binary, `encodePose` on the phone and `decodePose` on the screen; any other screen gets JSON, and a screen
+reads both. Version 1, little-endian:
+
+| Offset | Size | Field |
+|---|---|---|
+| 0 | 1 | magic `0xFB` |
+| 1 | 1 | codec version, 1 |
+| 2 | 1 | kind, 1 = pose |
+| 3 | 1 | body count, 0–4 |
+| 4 | 8 | `t`, float64 (ms on the phone's clock) |
+| 12 | 132 per body | 33 landmarks × uint32: bits 0–9 x·1000, 10–19 y·1000, 20–29 visibility·1000, 30–31 zero |
+
+So 12 + 132 × bodies bytes (540 for 4 bodies). Values are the thousandths `toPlayerSpace` rounds to, so a decoded
+pose holds exactly the numbers the JSON one would. `decodePose` returns null on anything else (wrong length,
+magic, version or kind, more than 4 bodies, a value over 1000, `t` not finite) and never throws.
+
+Most games need only [`@fabi-play/sdk`](https://www.npmjs.com/package/@fabi-play/sdk), which includes what it uses
+from this package.
+
+## License
+
+Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).