@npcify/web 0.1.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 ADDED
@@ -0,0 +1,113 @@
1
+ # @npcify/web
2
+
3
+ Add a Npcify character to any browser application with JavaScript. Includes VRM
4
+ rendering, animation, lip sync, live chat, baked conversations, and a canvas
5
+ integration. No Vue or React dependency.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ npm install @npcify/web
11
+ ```
12
+
13
+ Use an ESM-capable bundler, such as Vite. This package includes the required
14
+ Npcify runtime code; consumers do not need private workspace packages.
15
+
16
+ ## Plain JavaScript
17
+
18
+ Create a key in your character's **Export → API keys** tab. Choose the characters
19
+ that integration may access. Copy the key when created; it is shown only once.
20
+
21
+ ```html
22
+ <canvas id="npc" style="width: 100%; height: 480px; touch-action: none"></canvas>
23
+ <button id="start" disabled>Start conversation</button>
24
+ <div id="replies"></div>
25
+ <p id="status" role="status"></p>
26
+ <script type="module" src="/main.js"></script>
27
+ ```
28
+
29
+ ```js
30
+ // main.js
31
+ import { mountNpcify } from '@npcify/web'
32
+
33
+ const start = document.querySelector('#start')
34
+ const replies = document.querySelector('#replies')
35
+ const status = document.querySelector('#status')
36
+ const view = await mountNpcify({
37
+ canvas: document.querySelector('#npc'),
38
+ baseUrl: 'https://api.npcify.ai',
39
+ characterId: 'YOUR_CHARACTER_ID',
40
+ apiKey: 'YOUR_SCOPED_API_KEY',
41
+ serverRendering: false, // Use the setting from Export → Web SDK.
42
+ onError: (error) => { status.textContent = error.message },
43
+ })
44
+ const { npcify } = view
45
+ npcify.onOptionsReady(({ options }) => {
46
+ replies.replaceChildren()
47
+ for (const option of options) {
48
+ const button = document.createElement('button')
49
+ button.textContent = option.label
50
+ button.onclick = async () => {
51
+ replies.replaceChildren()
52
+ try { await npcify.sendMessage(option.label) }
53
+ catch (error) { status.textContent = error.message }
54
+ }
55
+ replies.append(button)
56
+ }
57
+ })
58
+ start.disabled = false
59
+ start.onclick = async () => {
60
+ start.disabled = true
61
+ try {
62
+ await npcify.unlockAudio()
63
+ await npcify.createConversation()
64
+ } catch (error) {
65
+ status.textContent = error.message
66
+ start.disabled = false
67
+ }
68
+ }
69
+ window.addEventListener('pagehide', () => { void view.dispose() }, { once: true })
70
+ ```
71
+
72
+ Run the included `examples/index.html` and `examples/main.js` with any ESM
73
+ bundler after replacing their configuration placeholders. Keys in browser code
74
+ are visible to visitors. Use narrow scopes; keep keys in your backend when they
75
+ must remain private. Calls made with a key are billed to its owner.
76
+
77
+ ## Runtime and lifecycle
78
+
79
+ - `mountNpcify({ canvas, baseUrl, characterId, apiKey, serverRendering })` returns
80
+ `{ npcify, dispose }` after loading. Give the canvas a nonzero CSS size.
81
+ - Call `unlockAudio()` during a user gesture before starting playback.
82
+ - `onOptionsReady` delivers choices after playback finishes. `sendMessage(label)`
83
+ selects a choice. Custom replies depend on the character configuration.
84
+ - `onStagingResult` delivers full results. `onCharacterReveal` supports subtitles.
85
+ - `dispose()` stops rendering, releases GPU resources, and disconnects chat.
86
+ Call it when navigating away or removing the canvas.
87
+ - `serverRendering: true` uses acknowledged WebP frames through an authenticated
88
+ render session. Protected VRM/VRMA files stay on the server. Remount after a
89
+ render connection error. This release does not use the hosted site's WebRTC
90
+ video transport.
91
+ - Baked characters load their exported graph and run without runtime generation;
92
+ baked playback requires browser rendering.
93
+ - Keys may cover multiple characters. Editing scopes, rotating, or deleting keys
94
+ affects subsequent requests and disconnects associated conversation sockets.
95
+ - ESM only; `require()` is not a supported package entry point. Browser APIs are
96
+ used when creating a view; do not call `mountNpcify` during server rendering.
97
+
98
+ For custom rendering, use the exported `Npcify` class (`apiToken` option), call
99
+ `loadAssets()`, add `npcify.vrm.scene` to your scene, and call
100
+ `npcify.update(deltaSeconds)` from your render loop. Do not update that VRM a
101
+ second time. Call `endConversation()` when finished.
102
+
103
+ ## Maintainer release
104
+
105
+ From the monorepo, run `pnpm -C packages/web typecheck`,
106
+ `pnpm -C packages/web build`, and `pnpm -C packages/web pack`. Inspect the tarball,
107
+ then test installing it in an empty project, importing its entry, resolving its
108
+ TypeScript types, and building the plain JavaScript example. Publish that
109
+ verified tarball using `npm publish <tarball> --access public`; npm may request
110
+ interactive 2FA. Check the registry version and install from the registry again.
111
+
112
+ Private Npcify dependencies are bundled into the ESM and declaration entry;
113
+ Third-party renderer and transport dependencies remain normal npm dependencies.