@vivi2d/web 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,160 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated in
+writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the
+Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,201 @@
+# @vivi2d/web
+
+Experimental browser SDK for embedding Vivi2D public-profile `.vivi` models.
+
+## Install / Import
+
+Before npm publication, use this package from the Vivi2D repository or from an
+explicit release tarball. After npm publication:
+
+```sh
+npm install @vivi2d/web@alpha
+```
+
+Alpha releases are intentionally published under the `alpha` dist-tag, not
+`latest`. Pin an exact version in production experiments if reproducibility
+matters.
+
+```ts
+import { createViviWebPlayer, loadViviWebModel } from "@vivi2d/web";
+```
+
+## Minimal Display
+
+```ts
+import { createViviWebPlayer, loadViviWebModel } from "@vivi2d/web";
+import { formatViviWebError } from "./error-copy";
+
+const canvas = document.querySelector<HTMLCanvasElement>("#vivi-canvas");
+const statusElement = document.querySelector<HTMLElement>("#status");
+if (!canvas || !statusElement) throw new Error("Missing sample elements");
+
+try {
+  const model = await loadViviWebModel("/generated-avatar.vivi");
+  const player = await createViviWebPlayer({
+    autoStart: true,
+    canvas,
+    model,
+  });
+  void player;
+} catch (error) {
+  statusElement.textContent = formatViviWebError(error).message;
+}
+```
+
+The full monorepo example lives at
+`examples/web-sdk-basic/README.md`. It includes ownership, HMR cleanup,
+`AbortController`, stale-load protection, input controls, and error-copy
+helpers. That example is repository content only; it is not packed into the npm
+tarball.
+
+## Load From A File Picker
+
+```ts
+const input = document.querySelector<HTMLInputElement>('input[type="file"]');
+input?.addEventListener("change", async () => {
+  const file = input.files?.[0];
+  if (!file) return;
+  const model = await loadViviWebModel(file);
+  await createViviWebPlayer({ canvas, model });
+});
+```
+
+Static servers should serve `.vivi` files as normal static assets. A generic
+binary MIME type is acceptable. Cross-origin model loading is the host
+application's responsibility and requires normal CORS headers.
+
+## Lifecycle Controls
+
+The basic SDK shape is:
+
+```text
+load model -> create player -> start/update/render -> set inputs -> dispose
+```
+
+`createViviWebPlayer` returns a `Promise<ViviWebPlayer>`. Apps should own one
+current player, abort in-flight loads before replacement, dispose old players,
+and ignore stale async completions after reload or dispose. The sample shows a
+single ownership helper for this pattern.
+
+Useful player methods:
+
+- `start()` and `stop()` control the automatic frame loop.
+- `update(deltaSeconds)` advances model state with a finite non-negative delta.
+- `render()` draws the current frame.
+- `resize(width, height)` changes the canvas size with positive integer bounds.
+- `dispose()` is idempotent and releases renderer resources.
+
+## Drive Inputs
+
+Use the public parameter list from the loaded model instead of hard-coding
+semantic parameter names:
+
+```ts
+for (const parameter of player.getParameters()) {
+  player.setInput(parameter.id, parameter.default);
+}
+
+player.setInputs({
+  [player.getParameters()[0]?.id ?? ""]: 0,
+});
+
+player.resetInputs();
+```
+
+Unknown input IDs are ignored by default. Pass `strictInputs: true` to
+`createViviWebPlayer` if the host app wants unknown input IDs to throw
+`VIVI_WEB_UNKNOWN_INPUT`.
+
+## Handle Errors
+
+SDK failures are normalized to `ViviWebError` with stable public codes. Host
+apps should display fixed copy derived from `error.code`; do not render raw
+messages, stack traces, causes, local paths, credentials, URLs, or model
+payload snippets.
+
+Common public codes include:
+
+- `VIVI_WEB_FETCH_FAILED`
+- `VIVI_WEB_PARSE_FAILED`
+- `VIVI_WEB_VALIDATION_FAILED`
+- `VIVI_WEB_INVALID_INPUT`
+- `VIVI_WEB_UNKNOWN_INPUT`
+- `VIVI_WEB_DISPOSED`
+- `VIVI_WEB_ABORTED`
+
+## Custom Element Alternative
+
+The root package import is side-effect free. Register the element explicitly:
+
+```ts
+import { defineViviModelElement } from "@vivi2d/web";
+
+defineViviModelElement();
+```
+
+```html
+<vivi-model src="./character.vivi" width="320" height="480" autoplay></vivi-model>
+```
+
+If you want import-time registration for a browser page, use the explicit
+side-effect entry point:
+
+```ts
+import "@vivi2d/web/auto-register";
+```
+
+The repository-local `packages/web/demo.html` remains the custom-element demo.
+Open it through the repository dev server, not as a standalone `file://` page.
+
+## Experimental Status And Compatibility
+
+This package is pre-1.0 and marked as experimental. The custom element name,
+methods, events, and file-format behavior may change before the first stable
+release.
+
+The guidance above is stable for the current Web SDK shape only. It does not
+promise native runtime ABI stability, official WASM binary stability, Unity SDK
+stability, or long-term low-level renderer internals.
+
+Browser assumptions:
+
+- Modern evergreen browser.
+- ES2020-compatible runtime.
+- WebGL-capable `HTMLCanvasElement`.
+- Keyboard and pointer interaction for sliders and controls.
+
+## API Reference
+
+Primary root exports:
+
+- `loadViviWebModel(source, options?)`
+- `createViviWebPlayer(options)`
+- `isViviWebError(error)`
+- `ViviWebError`
+- `ViviWebErrorCode`
+- `ViviWebModel`
+- `ViviWebPlayer`
+- `defineViviModelElement(tagName?)`
+- `ViviModelElement`
+
+`loadViviWebModel` accepts public `.vivi` sources, deep-clones object input,
+rejects private/authoring-only profiles, and returns an opaque `ViviWebModel`
+that external code cannot construct.
+
+Phase 1 targets `HTMLCanvasElement`. Worker-side `OffscreenCanvas` rendering is
+reserved for a later SDK phase.
+
+Thumbnails are bounded to 1,048,576 pixels and 2 MiB of data URL output. Apps
+with custom frame loops can pass a `scheduler` to `createViviWebPlayer` for
+deterministic tests or non-standard browser environments.
+
+## Security And Privacy
+
+- No telemetry or remote upload is enabled by default.
+- `.vivi` files are fetched only from sources provided by the host app.
+- The package is built as a browser-facing bundle and does not expose internal
+  workspace packages as public npm dependencies.
+- Runtime browser dependencies such as Pixi are bundled into the release files.
+  If this changes, the package must move the dependency into `dependencies` or
+  `peerDependencies`, update the tarball review, and refresh notices/SBOM
+  records before publication.

package/dist/CanvasPool-CASccukD.js

@@ -0,0 +1,48 @@
+import { D as n, aj as c, o as r } from "./index-CW8mx7yF.js";
+class l {
+  constructor(a) {
+    this._canvasPool = /* @__PURE__ */ Object.create(null), this.canvasOptions = a || {}, this.enableFullScreen = !1;
+  }
+  /**
+   * Creates texture with params that were specified in pool constructor.
+   * @param pixelWidth - Width of texture in pixels.
+   * @param pixelHeight - Height of texture in pixels.
+   */
+  _createCanvasAndContext(a, s) {
+    const t = n.get().createCanvas();
+    t.width = a, t.height = s;
+    const e = t.getContext("2d");
+    return { canvas: t, context: e };
+  }
+  /**
+   * Gets a Power-of-Two render texture or fullScreen texture
+   * @param minWidth - The minimum width of the render texture.
+   * @param minHeight - The minimum height of the render texture.
+   * @param resolution - The resolution of the render texture.
+   * @returns The new render texture.
+   */
+  getOptimalCanvasAndContext(a, s, t = 1) {
+    a = Math.ceil(a * t - 1e-6), s = Math.ceil(s * t - 1e-6), a = c(a), s = c(s);
+    const e = (a << 17) + (s << 1);
+    this._canvasPool[e] || (this._canvasPool[e] = []);
+    let o = this._canvasPool[e].pop();
+    return o || (o = this._createCanvasAndContext(a, s)), o;
+  }
+  /**
+   * Place a render texture back into the pool.
+   * @param canvasAndContext
+   */
+  returnCanvasAndContext(a) {
+    const s = a.canvas, { width: t, height: e } = s, o = (t << 17) + (e << 1);
+    a.context.resetTransform(), a.context.clearRect(0, 0, t, e), this._canvasPool[o].push(a);
+  }
+  clear() {
+    this._canvasPool = {};
+  }
+}
+const v = new l();
+r.register(v);
+export {
+  v as C
+};
+//# sourceMappingURL=CanvasPool-CASccukD.js.map

package/dist/CanvasPool-CASccukD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasPool-CASccukD.js","sources":["../../../node_modules/pixi.js/lib/rendering/renderers/shared/texture/CanvasPool.mjs"],"sourcesContent":["import { DOMAdapter } from '../../../../environment/adapter.mjs';\nimport { nextPow2 } from '../../../../maths/misc/pow2.mjs';\nimport { GlobalResourceRegistry } from '../../../../utils/pool/GlobalResourceRegistry.mjs';\n\n\"use strict\";\nclass CanvasPoolClass {\n  constructor(canvasOptions) {\n    this._canvasPool = /* @__PURE__ */ Object.create(null);\n    this.canvasOptions = canvasOptions || {};\n    this.enableFullScreen = false;\n  }\n  /**\n   * Creates texture with params that were specified in pool constructor.\n   * @param pixelWidth - Width of texture in pixels.\n   * @param pixelHeight - Height of texture in pixels.\n   */\n  _createCanvasAndContext(pixelWidth, pixelHeight) {\n    const canvas = DOMAdapter.get().createCanvas();\n    canvas.width = pixelWidth;\n    canvas.height = pixelHeight;\n    const context = canvas.getContext(\"2d\");\n    return { canvas, context };\n  }\n  /**\n   * Gets a Power-of-Two render texture or fullScreen texture\n   * @param minWidth - The minimum width of the render texture.\n   * @param minHeight - The minimum height of the render texture.\n   * @param resolution - The resolution of the render texture.\n   * @returns The new render texture.\n   */\n  getOptimalCanvasAndContext(minWidth, minHeight, resolution = 1) {\n    minWidth = Math.ceil(minWidth * resolution - 1e-6);\n    minHeight = Math.ceil(minHeight * resolution - 1e-6);\n    minWidth = nextPow2(minWidth);\n    minHeight = nextPow2(minHeight);\n    const key = (minWidth << 17) + (minHeight << 1);\n    if (!this._canvasPool[key]) {\n      this._canvasPool[key] = [];\n    }\n    let canvasAndContext = this._canvasPool[key].pop();\n    if (!canvasAndContext) {\n      canvasAndContext = this._createCanvasAndContext(minWidth, minHeight);\n    }\n    return canvasAndContext;\n  }\n  /**\n   * Place a render texture back into the pool.\n   * @param canvasAndContext\n   */\n  returnCanvasAndContext(canvasAndContext) {\n    const canvas = canvasAndContext.canvas;\n    const { width, height } = canvas;\n    const key = (width << 17) + (height << 1);\n    canvasAndContext.context.resetTransform();\n    canvasAndContext.context.clearRect(0, 0, width, height);\n    this._canvasPool[key].push(canvasAndContext);\n  }\n  clear() {\n    this._canvasPool = {};\n  }\n}\nconst CanvasPool = new CanvasPoolClass();\nGlobalResourceRegistry.register(CanvasPool);\n\nexport { CanvasPool, CanvasPoolClass };\n//# sourceMappingURL=CanvasPool.mjs.map\n"],"names":["CanvasPoolClass","canvasOptions","pixelWidth","pixelHeight","canvas","DOMAdapter","context","minWidth","minHeight","resolution","nextPow2","key","canvasAndContext","width","height","CanvasPool","GlobalResourceRegistry"],"mappings":";AAKA,MAAMA,EAAgB;AAAA,EACpB,YAAYC,GAAe;AACzB,SAAK,cAA8B,uBAAO,OAAO,IAAI,GACrD,KAAK,gBAAgBA,KAAiB,CAAA,GACtC,KAAK,mBAAmB;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,wBAAwBC,GAAYC,GAAa;AAC/C,UAAMC,IAASC,EAAW,IAAG,EAAG,aAAY;AAC5C,IAAAD,EAAO,QAAQF,GACfE,EAAO,SAASD;AAChB,UAAMG,IAAUF,EAAO,WAAW,IAAI;AACtC,WAAO,EAAE,QAAAA,GAAQ,SAAAE,EAAO;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,2BAA2BC,GAAUC,GAAWC,IAAa,GAAG;AAC9D,IAAAF,IAAW,KAAK,KAAKA,IAAWE,IAAa,IAAI,GACjDD,IAAY,KAAK,KAAKA,IAAYC,IAAa,IAAI,GACnDF,IAAWG,EAASH,CAAQ,GAC5BC,IAAYE,EAASF,CAAS;AAC9B,UAAMG,KAAOJ,KAAY,OAAOC,KAAa;AAC7C,IAAK,KAAK,YAAYG,CAAG,MACvB,KAAK,YAAYA,CAAG,IAAI,CAAA;AAE1B,QAAIC,IAAmB,KAAK,YAAYD,CAAG,EAAE,IAAG;AAChD,WAAKC,MACHA,IAAmB,KAAK,wBAAwBL,GAAUC,CAAS,IAE9DI;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA,uBAAuBA,GAAkB;AACvC,UAAMR,IAASQ,EAAiB,QAC1B,EAAE,OAAAC,GAAO,QAAAC,EAAM,IAAKV,GACpBO,KAAOE,KAAS,OAAOC,KAAU;AACvC,IAAAF,EAAiB,QAAQ,eAAc,GACvCA,EAAiB,QAAQ,UAAU,GAAG,GAAGC,GAAOC,CAAM,GACtD,KAAK,YAAYH,CAAG,EAAE,KAAKC,CAAgB;AAAA,EAC7C;AAAA,EACA,QAAQ;AACN,SAAK,cAAc,CAAA;AAAA,EACrB;AACF;AACK,MAACG,IAAa,IAAIf,EAAe;AACtCgB,EAAuB,SAASD,CAAU;","x_google_ignoreList":[0]}