@kalyptos/narcissus 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kalyptos
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# narcissus
 
-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 open library for Guldmund Trees: gaussian-splat scenes of any size, stored as static files and streamed by range request. narcissus holds the format, a WebGPU engine that draws it, a viewer element, and tools to check and publish a world.
+
+## Show a world
+
+```html
+<script
+	type="module"
+	src="https://cdn.jsdelivr.net/npm/@kalyptos/narcissus/dist/element/index.js"
+></script>
+<narcissus-viewer
+	src="https://example.com/world/world.json"
+	style="height: 100vh"
+></narcissus-viewer>
+```
+
+Or with a bundler:
+
+```sh
+npm install @kalyptos/narcissus
+```
+
+```ts
+import { createEngine, Controls } from '@kalyptos/narcissus';
+```
+
+## Check and publish a world
+
+```sh
+npx @kalyptos/narcissus validate ./world --deep
+npx @kalyptos/narcissus info ./world
+npx @kalyptos/narcissus export ./world -o level3.ply --level 3
+npx @kalyptos/narcissus publish ./world remote:bucket/world
+```
+
+## Read more
+
+- [docs/format.md](docs/format.md): the specification of Guldmund Trees
+- [docs/hosting.md](docs/hosting.md): how to serve, publish and show a world
+- [docs/architecture.md](docs/architecture.md): how the code is built, and how to add a source or a plugin
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Licence
+
+[BSD-3-Clause](LICENSE).

package/dist/adapters/disk.d.ts

@@ -0,0 +1,3 @@
+import { type Fetch } from '../ports.ts';
+/** a Fetch over the file system, for node; a url is a path */
+export declare const disk: Fetch;

package/dist/adapters/files.d.ts

@@ -0,0 +1,3 @@
+import { type Fetch } from '../ports.ts';
+/** a Fetch over files in memory, as a dropped folder holds them; a url is a file's path in entries */
+export declare function files(entries: ReadonlyMap<string, Blob>): Fetch;

package/dist/adapters/http.d.ts

@@ -0,0 +1,3 @@
+import { type Fetch } from '../ports.ts';
+/** a Fetch over http(s) with single closed ranges; a server that ignores the range is sliced */
+export declare const http: Fetch;

package/dist/adapters/memory.d.ts

@@ -0,0 +1,3 @@
+import type { Cache } from '../ports.ts';
+/** least recently used entries go first once bytes are exceeded */
+export declare function memoryCache(bytes: number): Cache;

package/dist/adapters/opfs.d.ts

@@ -0,0 +1,9 @@
+import type { Cache } from '../ports.ts';
+/**
+ * a Cache in the origin private file system, least recently used first past bytes; null when the
+ * browser offers none (private windows); every failure inside is a miss, never an error.
+ * shard k keeps its files in cache/k and must be their only user.
+ */
+export declare function opfsCache(bytes: number, shard: number): Promise<Cache | null>;
+/** removes everything in cache/ but the directories of shards 0 to shards - 1; never fails */
+export declare function pruneOpfs(shards: number): Promise<void>;

package/dist/cli/export.d.ts

@@ -0,0 +1 @@
+export declare function exportWorld(args: string[]): Promise<number>;

package/dist/cli/info.d.ts

@@ -0,0 +1 @@
+export declare function info(args: string[]): Promise<number>;

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { t as e } from "../ports-DZRKjdYD.js";
+import { t } from "../http-DL7R39Nc.js";
+import { a as n, r, t as i } from "../tools-DwOGah9N.js";
+import { createWriteStream as a, statSync as o } from "node:fs";
+import { pipeline as s } from "node:stream/promises";
+import { parseArgs as c } from "node:util";
+import { resolve as l } from "node:path";
+import { open as u } from "node:fs/promises";
+import { spawn as d } from "node:child_process";
+import { once as f } from "node:events";
+//#region src/adapters/disk.ts
+var p = async (t, n) => {
+	let r = await u(t).catch((n) => {
+		throw n.code === "ENOENT" ? new e(`no file ${t}`) : n;
+	});
+	try {
+		if (!n) return new Uint8Array(await r.readFile());
+		let e = new Uint8Array(n[1] - n[0]), { bytesRead: t } = await r.read(e, 0, e.length, n[0]);
+		return e.subarray(0, t);
+	} finally {
+		await r.close();
+	}
+}, m = /^https?:\/\//;
+function h(e) {
+	if (m.test(e)) return {
+		source: t,
+		url: e.endsWith("/") ? `${e}world.json` : e,
+		remote: !0
+	};
+	let n = l(e).replaceAll("\\", "/");
+	return {
+		source: p,
+		url: o(n, { throwIfNoEntry: !1 })?.isDirectory() ? `${n}/world.json` : n,
+		remote: !1
+	};
+}
+function g(e) {
+	let t = [
+		"bytes",
+		"KiB",
+		"MiB",
+		"GiB",
+		"TiB"
+	], n = Math.min(t.length - 1, Math.floor(Math.log2(Math.max(e, 1)) / 10));
+	return `${n === 0 ? e : (e / 2 ** (10 * n)).toFixed(1)} ${t[n]}`;
+}
+//#endregion
+//#region src/cli/export.ts
+var _ = "usage: narcissus export <world> -o <file.ply> [--level <g>] [--box <w,s,e,n>]";
+async function v(e) {
+	let { values: t, positionals: n } = c({
+		args: e,
+		options: {
+			out: {
+				type: "string",
+				short: "o"
+			},
+			level: {
+				type: "string",
+				default: "0"
+			},
+			box: { type: "string" }
+		},
+		allowPositionals: !0
+	}), r = Number(t.level), o = t.box?.split(",").map(Number), l = Number.isInteger(r) && r >= 0 && (!o || o.length === 4 && o.every(Number.isFinite));
+	if (n.length !== 1 || !t.out || !l) throw Error(_);
+	let { source: u, url: d } = h(n[0]), f = a(t.out);
+	return await s(i(u, d, {
+		level: r,
+		box: o
+	}), f), console.log(`${t.out}: ${g(f.bytesWritten)}`), 0;
+}
+//#endregion
+//#region src/cli/info.ts
+async function y(e) {
+	let { positionals: t } = c({
+		args: e,
+		allowPositionals: !0
+	});
+	if (t.length !== 1) throw Error("usage: narcissus info <world>");
+	let { source: n, url: i } = h(t[0]), { world: a, units: o, levels: s, bytes: l } = await r(n, i), { e: u, n: d, h: f } = a.extent, p = (e) => e.toLocaleString("en-US");
+	return console.log(`version  ${a.version}`), console.log(`crs      ${a.crs}, heights in ${a.height}`), console.log(`extent   e ${u[0]} to ${u[1]}, n ${d[0]} to ${d[1]}, h ${f[0]} to ${f[1]}`), console.log(`roots    ${a.roots.length}`), console.log(`packs    ${g(l)}`), o.forEach((e, t) => console.log(`units    level ${t}: ${p(e)}`)), s.forEach(({ pages: e, splats: t }, n) => {
+		console.log(`splats   level ${n}: ${p(t)} in ${p(e)} pages`);
+	}), 0;
+}
+//#endregion
+//#region src/cli/validate.ts
+async function b(e) {
+	let { values: t, positionals: r } = c({
+		args: e,
+		options: { deep: {
+			type: "boolean",
+			default: !1
+		} },
+		allowPositionals: !0
+	});
+	if (r.length !== 1) throw Error("usage: narcissus validate <world> [--deep]");
+	let { source: i, url: a, remote: o } = h(r[0]), s = process.stderr.isTTY, l = await n(i, a, {
+		deep: t.deep,
+		server: o,
+		progress: s ? ({ units: e }) => process.stderr.write(`\r${e} units`) : void 0
+	});
+	s && process.stderr.write("\r\x1B[K");
+	for (let { path: e, fault: t } of l.faults) console.log(`${e}: ${t}`);
+	let u = l.faults.length, d = u === 0 ? "no faults" : `${u} ${u === 1 ? "fault" : "faults"}`;
+	return console.log(`${l.units} units, ${l.files} files, ${g(l.bytes)}: ${d}`), u === 0 ? 0 : 1;
+}
+//#endregion
+//#region src/cli/publish.ts
+var x = "usage: narcissus publish <folder> <remote:path> [--url <world.json url>] [-- <rclone flags>]", S = "public, max-age=31536000, immutable", C = "no-cache", w = (e) => ["--header-upload", `Cache-Control: ${e}`];
+async function T(e) {
+	console.log(`rclone ${e.join(" ")}`);
+	let t = d("rclone", e, { stdio: "inherit" }), [n] = await f(t, "exit").catch((e) => {
+		throw e.code === "ENOENT" ? Error("rclone is not installed: https://rclone.org/install/") : e;
+	});
+	if (n !== 0) throw Error(`rclone ended with code ${n}`);
+}
+async function E(e) {
+	let t = e.indexOf("--"), n = t < 0 ? [] : e.slice(t + 1), { values: r, positionals: i } = c({
+		args: t < 0 ? e : e.slice(0, t),
+		options: { url: { type: "string" } },
+		allowPositionals: !0
+	});
+	if (i.length !== 2) throw Error(x);
+	let [a, o] = i.map((e) => e.replace(/\/+$/, ""));
+	return await b([a]) === 0 ? (await T([
+		"copy",
+		`${a}/u`,
+		`${o}/u`,
+		"--immutable",
+		...w(S),
+		...n
+	]), await T([
+		"copyto",
+		`${a}/world.json`,
+		`${o}/world.json`,
+		...w(C),
+		...n
+	]), r.url ? b([r.url]) : 0) : 1;
+}
+//#endregion
+//#region src/cli/main.ts
+var D = "usage: narcissus <command>\n\n  validate <world> [--deep]\n      checks every file of a world; --deep also reads every pack whole\n  info <world>\n      what a world holds\n  export <world> -o <file.ply> [--level <g>] [--box <w,s,e,n>]\n      one level as a gaussian-splat ply\n  publish <folder> <remote:path> [--url <world.json url>] [-- <rclone flags>]\n      uploads a world with rclone, unit files first\n\n  <world> is a folder, a world.json path or an http(s) url", O = {
+	validate: b,
+	info: y,
+	export: v,
+	publish: E
+}, [k, ...A] = process.argv.slice(2), j = O[k];
+j ? process.exitCode = await j(A).catch((e) => (console.error(e instanceof Error ? e.message : String(e)), 1)) : (console.error(D), process.exitCode = k === void 0 || k === "help" || k === "--help" ? 0 : 1);
+//#endregion

package/dist/cli/publish.d.ts

@@ -0,0 +1,2 @@
+/** checks the folder, uploads it so that no reader meets a world.json ahead of its unit files, then checks the url */
+export declare function publish(args: string[]): Promise<number>;

package/dist/cli/shared.d.ts

@@ -0,0 +1,8 @@
+import type { Fetch } from '../ports.ts';
+/** the source and world.json url of a world named by a url, a folder or a world.json path */
+export declare function target(world: string): {
+    source: Fetch;
+    url: string;
+    remote: boolean;
+};
+export declare function size(bytes: number): string;

package/dist/cli/validate.d.ts

@@ -0,0 +1 @@
+export declare function validate(args: string[]): Promise<number>;

package/dist/controls/controls.d.ts

@@ -0,0 +1,22 @@
+import type { Engine } from '../engine/index.ts';
+import { type Limits, type Pose } from './pose.ts';
+type Ground = (e: number, n: number) => number;
+/** metres one screen pixel spans at dist in a view pixels tall */
+export declare function metresPerPixel(dist: number, pixels: number): number;
+/** right, forward and up from the held key codes */
+export declare function flyAxes(keys: ReadonlySet<string>): [number, number, number];
+/** moves the shown pose toward the target over dt seconds; the target itself once settled */
+export declare function smooth(shown: Pose, target: Pose, dt: number, ground: Ground, limits?: Limits): Pose;
+/** map camera: left drag orbits, right/middle/shift drag pans the ground, wheel zooms, f flies */
+export declare class Controls {
+    #private;
+    constructor(canvas: HTMLCanvasElement, engine: Engine, ground: Ground, pose: Pose, limits?: Limits);
+    /** the pose the camera shows now */
+    get pose(): Pose;
+    /** fires on every frame the user moves the camera */
+    onChange(fn: () => void): () => void;
+    /** puts the focus on a ground point; heading and tilt stay, a far view closes in */
+    moveTo(e: number, n: number): void;
+    destroy(): void;
+}
+export {};

package/dist/controls/index.d.ts

@@ -0,0 +1,2 @@
+export { Controls } from './controls.ts';
+export * from './pose.ts';

package/dist/controls/pose.d.ts

@@ -0,0 +1,65 @@
+import type { Camera, World } from '../engine/index.ts';
+/** easting, northing and height in world coordinates, metres */
+export interface Point {
+    e: number;
+    n: number;
+    h: number;
+}
+/** a camera orbiting a focus point, in world coordinates */
+export interface Pose extends Point {
+    /** degrees clockwise from north, the direction the camera looks */
+    yaw: number;
+    /** degrees, negative looks down */
+    pitch: number;
+    /** metres from camera to focus */
+    dist: number;
+}
+/** vertical field of view, degrees */
+export declare const FOV = 45;
+export declare const defaultView: {
+    yaw: number;
+    pitch: number;
+    dist: number;
+};
+/** how far a pose may go */
+export interface Limits {
+    /** degrees */
+    pitch: readonly [number, number];
+    /** metres from camera to focus */
+    dist: readonly [number, number];
+    /** metres the camera stays above the ground under it */
+    clearance: number;
+    /** the lowest height of the camera */
+    floor: number;
+}
+export declare const LIMITS: Limits;
+/** the extent's centre when a root unit covers it, else the middle of the root unit nearest it, clipped to the extent */
+export declare function opening({ leaf, roots, extent }: Pick<World, 'leaf' | 'roots' | 'extent'>): Point;
+/** a pose from its text E,N,H,yaw,pitch,dist, as formatPose writes it; null when it is not one */
+export declare function parsePose(text: string): Pose | null;
+export declare function formatPose(p: Pose): string;
+export declare function clampPose(p: Pose, ground?: (e: number, n: number) => number, limits?: Limits): Pose;
+export declare function cameraOf(p: Pose): Point;
+/** the engine camera that shows a pose */
+export declare function viewOf(p: Pose): Camera;
+/** a place on screen in viewport heights from the centre, x right and y down */
+export interface Spot {
+    x: number;
+    y: number;
+}
+/** where a world point shows in p's view; fov vertical in degrees */
+export declare function project(p: Pose, fov: number, at: Point): Spot;
+/** the pose of a camera at from looking at to; yaw is 0 when looking straight down */
+export declare function lookAt(from: Point, to: Point): Pose;
+/** turns the view to yaw and pitch about the camera, which stays put */
+export declare function look(p: Pose, yaw: number, pitch: number, limits?: Limits): Pose;
+/** camera height above the focus, floored so a level view still has a scale */
+export declare function height(p: Pose): number;
+/** moves focus and camera together; right and forward follow the heading, metres */
+export declare function fly(p: Pose, right: number, forward: number, up: number): Pose;
+/** slides along the ground; metres of screen at the focus, so forward stretches as the view flattens */
+export declare function pan(p: Pose, right: number, forward: number): Pose;
+/** moves a toward b by fraction t: focus linearly, yaw the short way round, dist in log space */
+export declare function blend(a: Pose, b: Pose, t: number): Pose;
+/** close enough that the rest of the way is not visible */
+export declare function settled(a: Pose, b: Pose): boolean;