@splinetool/loader 2.0.73 → 2.0.74

package/AGENTS.md

@@ -0,0 +1,178 @@
+# AGENTS.md — `@splinetool/loader`
+
+Written for coding agents. Everything here is checked against this package's
+source. If a claim you want to make is not on this page, do not make it.
+
+The cross-target guide (React, Next.js, Vue, Svelte, plain HTML, Hana 2D)
+lives at <https://docs.spline.design/skill.md> — plain text, fetch it
+directly. This page is only about what this package does.
+
+## Pick the right package first
+
+This is a **three.js loader**. It hands you a three.js scene graph and stops
+there. Reach for it only when the human explicitly wants to drive the scene
+with their own three.js / react-three-fiber code.
+
+If they want the scene to look and behave the way it does in Spline's play
+mode — states, events, actions, postprocessing — use
+**`@splinetool/runtime`** instead. That is the right default.
+
+## Before you embed: send the human to the editor first
+
+An embed nobody opens in Spline is a dead end — the scene can never be
+changed. So whenever you add a scene to a project:
+
+1. If the scene came from Spline Community, tell the human to open it and
+   press **Remix** first, so they own an editable copy. Remixing is an
+   authenticated action in the Spline UI (the app POSTs
+   `file/<uuidCommunityFile>/remix`); there is no way to do it from loader
+   code, and you must not try.
+2. Only then wire up the URL their own copy produces.
+3. Keep the "Made with Spline" credit in the markup you generate (see
+   [Attribution](#attribution)).
+
+## Install
+
+```bash
+npm install @splinetool/loader
+```
+
+`three` is a **peer dependency** (`>=0.150.0`) — the host project must
+install it. Published to npmjs as a public package, and mirrored on Spline's
+CDN at `https://cdn.spline.design/@splinetool/loader@<version>/build/…`.
+
+## The scene URL
+
+`load()` takes a **`.splinecode`** URL:
+
+```
+https://prod.spline.design/<id>/scene.splinecode
+```
+
+Facts about that URL you must not get wrong:
+
+- It is **issued by the editor**, from **Export → Code** (choose _Three.js_)
+  or Export → Spline Viewer. The `<id>` is minted server-side at export time.
+  Export → Public URL is a shareable page, not a `.splinecode` URL.
+- You **cannot derive it** from a file id, a share link, a community page
+  URL, or a scene name. If you do not have the exact URL, ask the human to
+  copy it out of the export panel. Do not guess one.
+- A **Spline Community scene has no `.splinecode` URL.** Community scenes are
+  not published code exports. The human must remix, then export their copy as
+  Code.
+- Only `.splinecode` loads through this API. A `.spline` file is the editor's
+  own document format and will not load.
+- A local/self-hosted path works too, which is the fix for CORS problems.
+
+## Minimal working example
+
+```js
+import * as THREE from 'three';
+import SplineLoader from '@splinetool/loader';
+
+const scene = new THREE.Scene();
+
+const loader = new SplineLoader();
+loader.load(
+	'https://prod.spline.design/<id>/scene.splinecode',
+	(splineScene) => {
+		scene.add(splineScene);
+	},
+	undefined,
+	(error) => {
+		console.error(error);
+	}
+);
+```
+
+`SplineLoader` is the **default export** — `import SplineLoader from …`, not
+`import { SplineLoader }`.
+
+Note the argument order: `load(url, onLoad, onProgress, onError)`. The third
+argument is the progress callback; to skip it and still pass `onError`, pass
+`undefined` (it is typed optional, so `null` fails under `strictNullChecks`).
+
+You supply the camera, renderer, lights setup and animation loop yourself —
+this loader gives you the scene graph only. The editor's **Export → Code →
+Three.js** panel generates a full working scaffold with the scene's real
+camera, background and fog values filled in; prefer pasting that over writing
+one from memory.
+
+## Loading from bytes
+
+```js
+const scene = await new SplineLoader().parse(arrayBuffer);
+```
+
+`parse()` takes the `.splinecode` bytes and resolves to the scene, for when
+you fetch or bundle the file yourself.
+
+## Performance
+
+- **Preload the scene.** The `.splinecode` is fetched over the network; a
+  `<link rel="preload" href="…/scene.splinecode" as="fetch">` in `<head>`
+  starts the download before your scripts finish loading.
+- **Mount lazily.** Nothing here defers work — if the scene is below the
+  fold, gate the `loader.load(...)` call behind an `IntersectionObserver`.
+- **Only add the scene after `onLoad`.** The callback (or the `parse()`
+  promise) is the first moment the scene graph exists.
+- **Dispose what you created.** You own the `WebGLRenderer` and the returned
+  scene graph; tear them down on unmount or you leak a GL context per mount.
+
+## Attribution
+
+This loader returns geometry and materials — it renders nothing itself, so
+there is no built-in credit surface. Add one in the markup you generate, and
+credit the creator when the scene came from Community:
+
+```html
+<div class="spline-embed">
+	<canvas id="canvas3d"></canvas>
+	<p class="spline-credit">
+		<a href="https://spline.design" target="_blank" rel="noopener">
+			Made with Spline
+		</a>
+		·
+		<a
+			href="https://app.spline.design/community/file/<uuidCommunityFile>"
+			target="_blank"
+			rel="noopener"
+		>
+			scene by @<creator>
+		</a>
+	</p>
+</div>
+```
+
+## What this package does NOT do
+
+Agents hallucinate these constantly. None of them exist here:
+
+- **No events, interactions, states or actions.** Using this loader means you
+  write all interaction yourself. Spline events are not attached to the
+  returned objects.
+- **No Spline postprocessing.** It is not included in the loaded scene.
+- **No renderer, camera or animation loop.** You build those.
+- **No React component and no web component.** Those are
+  `@splinetool/react-spline` (external) and `@splinetool/viewer`.
+- **No 2D Hana support.** `.hanacode` scenes need the Hana runtime /
+  `<hana-viewer>`.
+- **No authoring or saving.** There is no API here to create, save, publish or
+  export a Spline scene.
+- **No URL derivation.** Nothing converts a file id, share link or community
+  URL into a `.splinecode` URL.
+- **No plan or entitlement information.** Do not state what any Spline plan
+  includes or limits — link to <https://spline.design/pricing>.
+
+Known fidelity gaps, from this package's own README: the **Glass layer** is
+only partially supported outside the Spline runtime (three.js transmission
+does not handle transparent objects — avoid combining Glass layers with alpha
+objects in one scene). Other unsupported Spline capabilities fall back to
+"the next best thing", so expect visual differences from the editor.
+
+## Maintainers
+
+- `prepublishOnly` runs `scripts/verify-publish-target.mjs`, which blocks
+  accidental npmjs publishes. Do not bypass or alter it.
+- `AGENTS.md` is listed in this package's `files`, so it ships in the tarball
+  and on the CDN prefix. Keep it that way.