@genex-ai/embed-sdk 0.31.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -40,6 +40,220 @@ sees; anyone else there resolves `{ staging: true }`. Names match
40
40
  `^[a-z0-9_-]{1,64}$`. Limits, quotas and endpoints:
41
41
  [§6a](../../CLI_INTEGRATION.md#6a-shared-collections--event-streams).
42
42
 
43
+ ## Entry URL and shells
44
+
45
+ SDK **0.32.0+**. The link a visitor opened is the game's: an invite
46
+ (`?room=abc`), a seed, a route (`#lobby`). The SDK keeps it across sign-in and
47
+ gives it back the same way wherever the game runs.
48
+
49
+ ```ts
50
+ import { getEntry, getShell, onShellClosing, savePlayerState } from "@genex-ai/embed-sdk";
51
+
52
+ const entry = getEntry(); // safe before initEmbed()
53
+ const room = entry.params.get("room"); // ?room=abc -> "abc"
54
+ const route = entry.hash; // #lobby -> "#lobby"
55
+ const from = entry.referrer; // "https://example.com", or null
56
+
57
+ if (getShell() === "app") hideInstallBanner();
58
+ onShellClosing(() => void savePlayerState(progress));
59
+ ```
60
+
61
+ `getShell()` answers which of the four shells the page is in. It is a fact
62
+ about the page, not a permission and not who is signed in.
63
+
64
+ | `getShell()` | The game is | `search` and `hash` are | `referrer` is |
65
+ | --- | --- | --- | --- |
66
+ | `page` | in a frame: its Genex game page, or any other page that embeds it | the frame's own address | the origin the game page passed on the frame's address |
67
+ | `standalone` | on its own address in a browser tab | its own address, with the fragment restored after the sign-in round trip | the origin carried through that round trip |
68
+ | `app` | inside the Genex mobile app | the address the app opened | `null`: the app passes none |
69
+ | `local` | on a dev server (`localhost`), in local test mode | the URL you typed | `document.referrer`'s origin |
70
+
71
+ `page` means a frame, whoever made it. Framed by another site, a game still
72
+ reads `page`, and the calls that need Genex around the frame
73
+ (`openExternal()`, `saveFile()`) resolve `unsupported`. `app` is read off the
74
+ WebView the Genex app runs games in (a top-level page with
75
+ `window.ReactNativeWebView`), whichever way the app opened the game; any other
76
+ React Native WebView reads the same, and the `app` answers below are the Genex
77
+ app's: in another wrapper `keepAwake(true)` still resolves `ok` without holding
78
+ the screen on.
79
+
80
+ **Read your link from `getEntry()`, not from `location` or
81
+ `document.referrer`.** A standalone visit goes through one sign-in round trip
82
+ (`/play/authorize`) and comes back with Genex's own fragment in the address
83
+ bar. `initEmbed()` removes it and puts the game's fragment back, but that
84
+ rewrite fires no `hashchange`, so code that read `location.hash` first saw the
85
+ wrong value and is never told. After the round trip `document.referrer` is
86
+ Genex, and inside the game page it always is. `getEntry()` gives the same
87
+ answer before and after `initEmbed()`.
88
+
89
+ What survives, and what does not:
90
+
91
+ - **Query.** The same pairs, in order and byte for byte (`?film` stays `?film`,
92
+ `%20` stays `%20`). Up to 1024 characters, not counting the `?`; a longer
93
+ query is dropped whole, never cut.
94
+ - **Fragment.** Up to 4096 characters.
95
+ - **Referrer.** The origin only, `http` or `https`, never a path or a query.
96
+ It is resolved once per browser tab and kept in the tab's `sessionStorage`,
97
+ so a reload answers the same; a second arrival in the same tab keeps the
98
+ first answer. Where the browser withholds that storage from the game (site
99
+ data blocked), nothing is kept and a reload answers `null`, or Genex's own
100
+ origin, not the site the visitor first came from. Treat it as attribution,
101
+ not proof: a link can claim any origin.
102
+ - **Reserved names.** `embed` and every key that starts with `genex_` belong to
103
+ the platform everywhere, in the query and in the fragment. `getEntry()`
104
+ leaves them out, and a fragment that contains `genex_` is not carried at
105
+ all. On a link to the game's page on Genex, and in the Genex app, `ref`,
106
+ `s`, `from`, `remix` and `slug` are the platform's too and do not reach the
107
+ game, though they do on the game's own address. On the game page the
108
+ fragment `#credits` opens Genex's own settings and is not carried either. A
109
+ link that has to work everywhere uses other names.
110
+
111
+ The platform is updated separately from your game. Where the game page, the
112
+ app or the sign-in round trip does not pass a value yet, `getEntry()` returns
113
+ `''` or `null` for it, never an error. A game published on an SDK older than
114
+ 0.32.0 does not get its fragment or referrer back: republish to pick this up.
115
+ On the game's own address Genex decides that from the range in the game's
116
+ `package.json` as `genex preview` / `genex publish` recorded it for the build:
117
+ `^0.32.0` counts, `^0.31.0` does not even when 0.32 is what got installed, and
118
+ `workspace:*` or `latest` do not.
119
+
120
+ `onShellClosing(cb)` runs `cb` when the page is being taken away: the
121
+ browser's `pagehide` (tab closed, reloaded, navigated away) and the Genex app
122
+ closing the game. It is called once per closing and returns an unsubscribe
123
+ function. On the browser's `pagehide` a small `savePlayerState()` started
124
+ there still lands. In the app that is not verified: the app takes the game
125
+ away a moment after the call. So it is the last chance to save, not the only
126
+ one, and a phone can also drop a backgrounded tab without telling the page:
127
+ save as the game goes. A game cannot block the close or ask the player to
128
+ confirm it.
129
+
130
+ ## Platform capabilities
131
+
132
+ SDK **0.32.0+**. The browser gives a page different powers in each shell. The
133
+ Genex game page frames a game in a sandbox that withholds new windows,
134
+ downloads and navigating the page around it, and the Genex app is one WebView
135
+ that never leaves the game. So `window.open()` or a click on `<a download>`
136
+ works on the game's own link and silently does nothing on Genex. Use these
137
+ instead: one call each, the same in every shell.
138
+
139
+ ```ts
140
+ import { share, copyText, openExternal, saveFile, setFullscreen, keepAwake, haptic, supports } from "@genex-ai/embed-sdk";
141
+
142
+ inviteButton.addEventListener("click", async () => {
143
+ const { status, url } = await share({ text: "Join my room", params: { room } });
144
+ if (status === "copied") toast("Link copied");
145
+ if (status === "unavailable") showLink(url);
146
+ });
147
+
148
+ discordButton.addEventListener("click", async () => {
149
+ const result = await openExternal("https://discord.gg/my-server");
150
+ if (!result.ok && result.error !== "dismissed") showLink("discord.gg/my-server");
151
+ });
152
+ ```
153
+
154
+ **Call them from a click or tap handler, before any `await`.** The browser
155
+ lets a page share, copy, open a tab or go fullscreen only while a click is
156
+ being handled, and one click buys one action. Inside the game page that same
157
+ click is what lets Genex act for the game, so the SDK sends its request before
158
+ the call returns.
159
+
160
+ Every function resolves. None rejects, so there is nothing to `catch`. A call
161
+ that waits for Genex waits against a timer (`timeout` below). `share()` is the
162
+ one wait without a timer: it resolves when the player picks a target in the
163
+ system share sheet or closes it, however long they keep it open. `share()`
164
+ resolves `{ status, url }`; the others resolve `{ ok: true }` or
165
+ `{ ok: false, error }`; `haptic()` returns nothing.
166
+
167
+ | Function | On the Genex game page (`page`) | On its own address (`standalone`, `local`) | In the Genex app (`app`) |
168
+ | --- | --- | --- | --- |
169
+ | `share({ text?, params? })` | the system share sheet where the browser offers one, else the link is copied | the same | the same |
170
+ | `copyText(text)` | the clipboard | the clipboard | the clipboard, where the app's web view has one |
171
+ | `keepAwake(on)` | a screen wake lock | a screen wake lock | `ok`: the app already keeps the screen on |
172
+ | `haptic(kind)` | a vibration where the browser has one | the same | nothing |
173
+ | `openExternal(url)` | Genex asks the player, then opens a new tab | a new tab | `unsupported` |
174
+ | `saveFile(blob, name)` | Genex asks the player, then saves the file | a download | `unsupported` |
175
+ | `setFullscreen(on)` | the game page's own fullscreen | the browser's fullscreen | `unsupported`: the game already has the whole screen |
176
+
177
+ - **`share()`** builds the link itself; a game never supplies it. It is the
178
+ game's page on Genex where Genex serves the live build or frames the game,
179
+ and otherwise the address the game is on: a creator's domain, a preview
180
+ address, a dev server, or a frame on another site. Your `params` are added
181
+ to it, and whoever opens the link reads them back with `getEntry().params`.
182
+ `embed`, `ref`, `s`, `from`, `remix`, `slug` and every name starting
183
+ `genex_` are reserved and left out, and params that would make the query
184
+ longer than 1024 characters (not counting the `?`) are left out whole (one
185
+ console warning says so). `text` goes to the share sheet only. `status` is
186
+ `shared`, `copied`, `dismissed` (the player closed the sheet) or
187
+ `unavailable` (show `url` yourself). In local test mode the sheet is never
188
+ opened, so an automated browser is not left waiting on it: the link is
189
+ copied.
190
+ - **`openExternal()`** takes an absolute `https://` URL of at most 2048
191
+ characters. On the game page Genex shows the player where the link goes and
192
+ opens it on their click; `dismissed` is their no.
193
+ - **`saveFile()`** takes a `Blob` of at most 50 MB whose `type` is PNG, JPEG,
194
+ WebP, WebM, MP4, JSON or plain text, and a file name of 1 to 128 characters
195
+ with no `/` or `\` in it. The same bounds apply in every shell, so a save
196
+ that works on the game's own link works on Genex. The saved file's extension
197
+ follows the type: `saveFile(pngBlob, "boss fight")` saves `boss fight.png`.
198
+ - **`setFullscreen()`** on the game page is the page's fullscreen, the one its
199
+ own button gives, with the page's controls on top of the game. A game's own
200
+ `requestFullscreen()` still works there for the frame's document. Entering
201
+ needs the player's click, tap or key press inside the game, and a click on
202
+ the page around the game in the five seconds before does not count; leaving
203
+ needs nothing. Nothing stays fullscreen while Genex shows the player a sheet
204
+ (a link, a file, a purchase): a fullscreen asked for in the same tick as one
205
+ of those is left again and answers `busy`.
206
+ - **`keepAwake(true)`** holds until `keepAwake(false)`. The browser drops the
207
+ lock whenever the tab is hidden, and the SDK takes it again when the player
208
+ comes back.
209
+ - **`haptic(kind)`** takes `selection`, `light`, `medium`, `heavy`, `success`,
210
+ `warning` or `error`. It buzzes on Android browsers after the player's first
211
+ tap, and does nothing on an iPhone or in the Genex app. Never make it the
212
+ only signal that something happened.
213
+
214
+ **Pointer lock.** Genex asks the player on a sheet drawn around the game, and
215
+ the player needs a cursor to answer. A game that holds the pointer (mouse
216
+ look) keeps it, hidden, until the lock ends, and only the game's own document
217
+ can end it. So on the game page the SDK calls `document.exitPointerLock()`
218
+ before it asks for a link (`openExternal()`), a file (`saveFile()`), a
219
+ purchase (`buy()`), a generation approval or a budget. The game hears
220
+ `pointerlockchange`, as it does when the player presses Escape: take the lock
221
+ again on the next click. `setFullscreen()` does not release it. A game built
222
+ on an SDK older than 0.32.0 does not do this: its lock stays until the player
223
+ presses Escape.
224
+
225
+ `supports(name)` answers, synchronously, whether a call can do its job here:
226
+ `share`, `copy` (`copyText`), `awake` (`keepAwake`), `haptic`, `open`
227
+ (`openExternal`), `save` (`saveFile`), `fullscreen` (`setFullscreen`). Use it
228
+ to decide whether to draw a button. On the game page the answer for `open`,
229
+ `save` and the page's fullscreen arrives with the identity handshake, so ask
230
+ after `waitForPlayer()`. It is a hint; the call's own result is the truth.
231
+
232
+ Why a call did not happen, as `error`:
233
+
234
+ | `error` | It means | What to do |
235
+ | --- | --- | --- |
236
+ | `unsupported` | this shell or this browser cannot do it | hide the button, or show the link or the data another way |
237
+ | `needs_gesture` | the browser wants a click or a tap behind the call. On the game page `setFullscreen(true)` also answers it when no click, tap or key press of the player's INSIDE the game stands behind it, which includes the five seconds after they clicked or typed on the page around the game | call it straight from the handler, before any `await`, and keep the button up: the player's next click in the game works |
238
+ | `dismissed` | the player said no | nothing; it is not an error |
239
+ | `busy` | another request is still waiting for the player's answer, or a `setFullscreen(true)` the browser has not answered yet | ignore the extra click |
240
+ | `rate_limited` | the game asked too often | do not call these on a timer |
241
+ | `invalid_request` | the arguments are outside the bounds above | fix the call |
242
+ | `too_large` | the file is over 50 MB | save something smaller |
243
+ | `timeout` | Genex did not answer: within 3 seconds for fullscreen, three minutes for a link or a file, which wait for the player | treat it like `unsupported` for this click |
244
+
245
+ `unsupported` and `timeout` are normal answers, not bugs. The platform is
246
+ updated separately from your game: on a game page that does not take these
247
+ requests yet, `openExternal()` and `saveFile()` resolve `unsupported` without
248
+ asking, and `setFullscreen()` fullscreens the frame's own document as a game
249
+ could before.
250
+
251
+ What has no call here, on purpose. `alert()`, `confirm()`, `prompt()` and
252
+ "Leave site?" prompts show nothing on the game page: draw dialogs in the game,
253
+ and save from `onShellClosing()`. Reading the clipboard is not available: listen
254
+ for the `paste` event. Sign-in popups for other services, notifications and
255
+ the tab's title are not available to a framed game.
256
+
43
257
  ## Generate during play
44
258
 
45
259
  Runtime generation requires a signed-in player in a published game and an