@rpgjs/map-builder 0.0.0-stage → 5.0.0

package/dist/model/parse.js

@@ -0,0 +1,165 @@
+import { cloneJson, isJsonObject, isJsonValue, isPlainObject } from "./json.js";
+import "./definition.js";
+import { MapDefinitionError } from "./errors.js";
+//#region src/model/parse.ts
+/** Migrations keyed by the version they upgrade *from*. Empty until version 2 exists. */
+var defaultMapMigrations = {};
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var isPositive = (value) => isFiniteNumber(value) && value > 0;
+/** A positive number, or `[x, y]` of positive numbers. */
+var isScale = (value) => isPositive(value) || Array.isArray(value) && value.length === 2 && value.every(isPositive);
+var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+/** Problems found in one element or event, with paths relative to `path`. */
+function checkPlaced(value, path, kind) {
+	if (!isPlainObject(value)) return [{
+		path,
+		message: `${kind} must be an object`
+	}];
+	const issues = [];
+	if (!isNonEmptyString(value.id)) issues.push({
+		path: `${path}.id`,
+		message: "must be a non-empty string"
+	});
+	if (!isNonEmptyString(value.kind)) issues.push({
+		path: `${path}.kind`,
+		message: "must be a non-empty string"
+	});
+	if (!isFiniteNumber(value.x)) issues.push({
+		path: `${path}.x`,
+		message: "must be a finite number"
+	});
+	if (!isFiniteNumber(value.y)) issues.push({
+		path: `${path}.y`,
+		message: "must be a finite number"
+	});
+	if (value.data !== void 0 && !isJsonObject(value.data)) issues.push({
+		path: `${path}.data`,
+		message: "must be a JSON object"
+	});
+	if (kind === "event" && value.graphic !== void 0 && !isNonEmptyString(value.graphic)) issues.push({
+		path: `${path}.graphic`,
+		message: "must be a non-empty string"
+	});
+	if (kind === "element" && value.scale !== void 0 && !isScale(value.scale)) issues.push({
+		path: `${path}.scale`,
+		message: "must be a positive number or [x, y] of positive numbers"
+	});
+	if (kind === "element" && value.depth !== void 0) if (!isPlainObject(value.depth)) issues.push({
+		path: `${path}.depth`,
+		message: "must be an object"
+	});
+	else for (const key of [
+		"z",
+		"anchorY",
+		"height"
+	]) {
+		const field = value.depth[key];
+		if (field !== void 0 && !isFiniteNumber(field)) issues.push({
+			path: `${path}.depth.${key}`,
+			message: "must be a finite number"
+		});
+	}
+	return issues;
+}
+function checkList(value, path, kind, issues) {
+	if (!Array.isArray(value)) {
+		issues.push({
+			path,
+			message: "must be an array"
+		});
+		return;
+	}
+	const seen = /* @__PURE__ */ new Set();
+	value.forEach((item, index) => {
+		const itemPath = `${path}[${index}]`;
+		issues.push(...checkPlaced(item, itemPath, kind));
+		const id = isPlainObject(item) ? item.id : void 0;
+		if (isNonEmptyString(id)) {
+			if (seen.has(id)) issues.push({
+				path: `${itemPath}.id`,
+				message: `duplicate ${kind} id "${id}"`
+			});
+			seen.add(id);
+		}
+	});
+}
+function migrate(raw, options) {
+	const current = options.currentVersion ?? 1;
+	const migrations = options.migrations ?? defaultMapMigrations;
+	let version = raw.version;
+	if (!Number.isInteger(version) || version < 1) throw new MapDefinitionError([{
+		path: "version",
+		message: "must be a positive integer"
+	}]);
+	if (version > current) throw new MapDefinitionError([{
+		path: "version",
+		message: `version ${version} is newer than the supported version ${current}; upgrade @rpgjs/map-builder`
+	}]);
+	let out = raw;
+	while (version < current) {
+		const step = migrations[version];
+		if (!step) throw new MapDefinitionError([{
+			path: "version",
+			message: `no migration from version ${version} to ${version + 1}`
+		}]);
+		out = {
+			...step(out),
+			version: version + 1
+		};
+		version = out.version;
+	}
+	return out;
+}
+/** Canonical form: an empty `data` object is omitted. */
+function canonicalPlaced(item) {
+	return Object.fromEntries(Object.entries(item).filter(([key, value]) => value !== void 0 && !(key === "data" && isPlainObject(value) && Object.keys(value).length === 0)).map(([key, value]) => [key, isJsonValue(value) ? cloneJson(value) : value]));
+}
+/**
+* Validates, migrates and copies a raw definition (for instance parsed JSON).
+*
+* - The result shares no structure with the input.
+* - Fields unknown to this version are preserved, so an older tool never destroys
+*   data written by a newer one.
+* - Throws {@link MapDefinitionError} listing every problem found.
+*/
+function parseMapDefinition(raw, options = {}) {
+	if (!isPlainObject(raw)) throw new MapDefinitionError([{
+		path: "",
+		message: "must be an object"
+	}]);
+	const source = migrate(raw, options);
+	const issues = [];
+	if (!isNonEmptyString(source.id)) issues.push({
+		path: "id",
+		message: "must be a non-empty string"
+	});
+	const size = source.size;
+	if (!Array.isArray(size) || size.length !== 2 || !size.every((n) => isFiniteNumber(n) && n > 0)) issues.push({
+		path: "size",
+		message: "must be [width, height] in pixels, both positive"
+	});
+	if (source.tileSize !== void 0 && !(isFiniteNumber(source.tileSize) && source.tileSize > 0)) issues.push({
+		path: "tileSize",
+		message: "must be a positive number"
+	});
+	checkList(source.elements ?? [], "elements", "element", issues);
+	checkList(source.events ?? [], "events", "event", issues);
+	if (source.extensions !== void 0) {
+		if (!isPlainObject(source.extensions) || !isJsonValue(source.extensions)) issues.push({
+			path: "extensions",
+			message: "must be a JSON object keyed by feature id"
+		});
+	}
+	if (issues.length > 0) throw new MapDefinitionError(issues);
+	const { elements = [], events = [], extensions, ...rest } = source;
+	return Object.fromEntries([
+		...Object.entries(rest).filter(([, value]) => value !== void 0).map(([key, value]) => [key, isJsonValue(value) ? cloneJson(value) : value]),
+		["elements", elements.map(canonicalPlaced)],
+		["events", events.map(canonicalPlaced)],
+		...extensions !== void 0 ? [["extensions", cloneJson(extensions)]] : []
+	]);
+}
+//#endregion
+export { checkPlaced, defaultMapMigrations, isScale, parseMapDefinition };
+
+//# sourceMappingURL=parse.js.map

package/dist/model/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","names":[],"sources":["../../src/model/parse.ts"],"sourcesContent":["import { MAP_DEFINITION_VERSION, type MapDefinition } from \"./definition\";\nimport { MapDefinitionError, type MapIssue } from \"./errors\";\nimport { cloneJson, isJsonObject, isJsonValue, isPlainObject, type JsonValue } from \"./json\";\n\n/** Upgrades a raw definition from version `n` to version `n + 1`. */\nexport type MapMigration = (raw: Record<string, unknown>) => Record<string, unknown>;\n\n/** Migrations keyed by the version they upgrade *from*. Empty until version 2 exists. */\nexport const defaultMapMigrations: Readonly<Record<number, MapMigration>> = {};\n\nexport interface ParseMapOptions {\n  readonly migrations?: Readonly<Record<number, MapMigration>>;\n  readonly currentVersion?: number;\n}\n\nconst isFiniteNumber = (value: unknown): value is number => typeof value === \"number\" && Number.isFinite(value);\nconst isPositive = (value: unknown): value is number => isFiniteNumber(value) && value > 0;\n/** A positive number, or `[x, y]` of positive numbers. */\nexport const isScale = (value: unknown): boolean =>\n  isPositive(value) || (Array.isArray(value) && value.length === 2 && value.every(isPositive));\nconst isNonEmptyString = (value: unknown): value is string => typeof value === \"string\" && value.length > 0;\n\n/** Problems found in one element or event, with paths relative to `path`. */\nexport function checkPlaced(value: unknown, path: string, kind: \"element\" | \"event\"): MapIssue[] {\n  if (!isPlainObject(value)) return [{ path, message: `${kind} must be an object` }];\n  const issues: MapIssue[] = [];\n  if (!isNonEmptyString(value.id)) issues.push({ path: `${path}.id`, message: \"must be a non-empty string\" });\n  if (!isNonEmptyString(value.kind)) issues.push({ path: `${path}.kind`, message: \"must be a non-empty string\" });\n  if (!isFiniteNumber(value.x)) issues.push({ path: `${path}.x`, message: \"must be a finite number\" });\n  if (!isFiniteNumber(value.y)) issues.push({ path: `${path}.y`, message: \"must be a finite number\" });\n  if (value.data !== undefined && !isJsonObject(value.data)) {\n    issues.push({ path: `${path}.data`, message: \"must be a JSON object\" });\n  }\n  if (kind === \"event\" && value.graphic !== undefined && !isNonEmptyString(value.graphic)) {\n    issues.push({ path: `${path}.graphic`, message: \"must be a non-empty string\" });\n  }\n  if (kind === \"element\" && value.scale !== undefined && !isScale(value.scale)) {\n    issues.push({ path: `${path}.scale`, message: \"must be a positive number or [x, y] of positive numbers\" });\n  }\n  if (kind === \"element\" && value.depth !== undefined) {\n    if (!isPlainObject(value.depth)) {\n      issues.push({ path: `${path}.depth`, message: \"must be an object\" });\n    } else {\n      for (const key of [\"z\", \"anchorY\", \"height\"] as const) {\n        const field = value.depth[key];\n        if (field !== undefined && !isFiniteNumber(field)) {\n          issues.push({ path: `${path}.depth.${key}`, message: \"must be a finite number\" });\n        }\n      }\n    }\n  }\n  return issues;\n}\n\nfunction checkList(value: unknown, path: string, kind: \"element\" | \"event\", issues: MapIssue[]): void {\n  if (!Array.isArray(value)) {\n    issues.push({ path, message: \"must be an array\" });\n    return;\n  }\n  const seen = new Set<string>();\n  value.forEach((item, index) => {\n    const itemPath = `${path}[${index}]`;\n    issues.push(...checkPlaced(item, itemPath, kind));\n    const id = isPlainObject(item) ? item.id : undefined;\n    if (isNonEmptyString(id)) {\n      if (seen.has(id)) issues.push({ path: `${itemPath}.id`, message: `duplicate ${kind} id \"${id}\"` });\n      seen.add(id);\n    }\n  });\n}\n\nfunction migrate(raw: Record<string, unknown>, options: ParseMapOptions): Record<string, unknown> {\n  const current = options.currentVersion ?? MAP_DEFINITION_VERSION;\n  const migrations = options.migrations ?? defaultMapMigrations;\n  let version = raw.version;\n  if (!Number.isInteger(version) || (version as number) < 1) {\n    throw new MapDefinitionError([{ path: \"version\", message: \"must be a positive integer\" }]);\n  }\n  if ((version as number) > current) {\n    throw new MapDefinitionError([\n      {\n        path: \"version\",\n        message: `version ${version} is newer than the supported version ${current}; upgrade @rpgjs/map-builder`,\n      },\n    ]);\n  }\n  let out = raw;\n  while ((version as number) < current) {\n    const step = migrations[version as number];\n    if (!step) {\n      throw new MapDefinitionError([\n        { path: \"version\", message: `no migration from version ${version} to ${(version as number) + 1}` },\n      ]);\n    }\n    out = { ...step(out), version: (version as number) + 1 };\n    version = out.version;\n  }\n  return out;\n}\n\n/** Canonical form: an empty `data` object is omitted. */\nfunction canonicalPlaced<T extends Record<string, unknown>>(item: T): T {\n  return Object.fromEntries(\n    Object.entries(item)\n      .filter(([key, value]) => value !== undefined && !(key === \"data\" && isPlainObject(value) && Object.keys(value).length === 0))\n      .map(([key, value]) => [key, isJsonValue(value) ? cloneJson(value) : value]),\n  ) as T;\n}\n\n/**\n * Validates, migrates and copies a raw definition (for instance parsed JSON).\n *\n * - The result shares no structure with the input.\n * - Fields unknown to this version are preserved, so an older tool never destroys\n *   data written by a newer one.\n * - Throws {@link MapDefinitionError} listing every problem found.\n */\nexport function parseMapDefinition(raw: unknown, options: ParseMapOptions = {}): MapDefinition {\n  if (!isPlainObject(raw)) throw new MapDefinitionError([{ path: \"\", message: \"must be an object\" }]);\n  const source = migrate(raw, options);\n\n  const issues: MapIssue[] = [];\n  if (!isNonEmptyString(source.id)) issues.push({ path: \"id\", message: \"must be a non-empty string\" });\n\n  const size = source.size;\n  if (!Array.isArray(size) || size.length !== 2 || !size.every((n) => isFiniteNumber(n) && n > 0)) {\n    issues.push({ path: \"size\", message: \"must be [width, height] in pixels, both positive\" });\n  }\n  if (source.tileSize !== undefined && !(isFiniteNumber(source.tileSize) && source.tileSize > 0)) {\n    issues.push({ path: \"tileSize\", message: \"must be a positive number\" });\n  }\n  checkList(source.elements ?? [], \"elements\", \"element\", issues);\n  checkList(source.events ?? [], \"events\", \"event\", issues);\n  if (source.extensions !== undefined) {\n    if (!isPlainObject(source.extensions) || !isJsonValue(source.extensions)) {\n      issues.push({ path: \"extensions\", message: \"must be a JSON object keyed by feature id\" });\n    }\n  }\n  if (issues.length > 0) throw new MapDefinitionError(issues);\n\n  const { elements = [], events = [], extensions, ...rest } = source as Record<string, unknown> & {\n    elements?: Record<string, unknown>[];\n    events?: Record<string, unknown>[];\n    extensions?: Record<string, JsonValue>;\n  };\n  const definition = Object.fromEntries([\n    ...Object.entries(rest)\n      .filter(([, value]) => value !== undefined)\n      .map(([key, value]) => [key, isJsonValue(value) ? cloneJson(value) : value]),\n    [\"elements\", elements.map(canonicalPlaced)],\n    [\"events\", events.map(canonicalPlaced)],\n    ...(extensions !== undefined ? [[\"extensions\", cloneJson(extensions)]] : []),\n  ]);\n  return definition as unknown as MapDefinition;\n}\n"],"mappings":"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"}

package/dist/model/patches.d.ts

@@ -0,0 +1,100 @@
+import { MapDepth, MapElement, MapEvent, MapScale, MapState } from './definition';
+import { MapRejection, RejectionCode } from './errors';
+import { JsonObject, JsonValue } from './json';
+/**
+ * Every patch type the model understands, mapped to its payload.
+ *
+ * The registry is open: a feature adds its own patch types by merging into this
+ * interface, and gets them checked everywhere `MapPatch` is used.
+ *
+ * ```ts
+ * declare module "@rpgjs/map-builder/model" {
+ *   interface PatchRegistry {
+ *     "tilling.till": { x: number; y: number };
+ *   }
+ * }
+ * ```
+ *
+ * Payloads must be JSON-serializable: patches are sent over the network, stored
+ * and replayed.
+ */
+export interface PatchRegistry {
+    "element.add": {
+        readonly element: MapElement;
+        readonly index?: number;
+    };
+    "element.remove": {
+        readonly id: string;
+    };
+    "element.move": {
+        readonly id: string;
+        readonly x: number;
+        readonly y: number;
+    };
+    /** `kind` replaces the asset reference. `depth: null` and `scale: null` clear them. */
+    "element.update": {
+        readonly id: string;
+        readonly set: {
+            readonly kind?: string;
+            readonly depth?: MapDepth | null;
+            readonly scale?: MapScale | null;
+        };
+    };
+    /** Merges `set` into the element data, then removes the `unset` keys. */
+    "element.data": {
+        readonly id: string;
+        readonly set?: JsonObject;
+        readonly unset?: readonly string[];
+    };
+    "event.add": {
+        readonly event: MapEvent;
+        readonly index?: number;
+    };
+    "event.remove": {
+        readonly id: string;
+    };
+    "event.move": {
+        readonly id: string;
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Sets the data a feature owns. An absent `value` removes it. */
+    "extension.set": {
+        readonly id: string;
+        readonly value?: JsonValue;
+    };
+}
+export type PatchType = keyof PatchRegistry & string;
+export type MapPatchOf<K extends PatchType> = {
+    readonly type: K;
+    /**
+     * Revision the patch was computed against. The authority rejects (or rebases)
+     * a patch built on a stale revision.
+     */
+    readonly baseRevision?: number;
+} & PatchRegistry[K];
+/** Discriminated union on `type`, derived from the registry. */
+export type MapPatch = {
+    [K in PatchType]: MapPatchOf<K>;
+}[PatchType];
+export type PatchOutcome = {
+    readonly ok: true;
+    readonly state: MapState;
+    /** Patches that undo this one, in the order they must be applied. */
+    readonly inverse: readonly MapPatch[];
+} | {
+    readonly ok: false;
+    readonly rejection: MapRejection;
+};
+/** How a patch type changes the state, and how it is undone. Pure: never mutate `state`. */
+export interface PatchHandler<K extends PatchType> {
+    apply(state: MapState, patch: MapPatchOf<K>): PatchOutcome;
+}
+export type PatchHandlers = {
+    readonly [K in PatchType]?: PatchHandler<K>;
+};
+export declare const patchOk: (state: MapState, inverse: readonly MapPatch[]) => PatchOutcome;
+export declare const patchFail: (code: RejectionCode, message: string) => PatchOutcome;
+/** Declares handlers with their types checked against the registry. */
+export declare function definePatchHandlers(handlers: PatchHandlers): PatchHandlers;
+//# sourceMappingURL=patches.d.ts.map

package/dist/model/patches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patches.d.ts","sourceRoot":"","sources":["../../src/model/patches.ts"],"names":[],"mappings":"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"}

package/dist/model/patches.js

@@ -0,0 +1,21 @@
+//#region src/model/patches.ts
+var patchOk = (state, inverse) => ({
+	ok: true,
+	state,
+	inverse
+});
+var patchFail = (code, message) => ({
+	ok: false,
+	rejection: {
+		code,
+		message
+	}
+});
+/** Declares handlers with their types checked against the registry. */
+function definePatchHandlers(handlers) {
+	return handlers;
+}
+//#endregion
+export { definePatchHandlers, patchFail, patchOk };
+
+//# sourceMappingURL=patches.js.map

package/dist/model/patches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patches.js","names":[],"sources":["../../src/model/patches.ts"],"sourcesContent":["import type { MapDepth, MapElement, MapEvent, MapScale, MapState } from \"./definition\";\nimport type { MapRejection, RejectionCode } from \"./errors\";\nimport type { JsonObject, JsonValue } from \"./json\";\n\n/**\n * Every patch type the model understands, mapped to its payload.\n *\n * The registry is open: a feature adds its own patch types by merging into this\n * interface, and gets them checked everywhere `MapPatch` is used.\n *\n * ```ts\n * declare module \"@rpgjs/map-builder/model\" {\n *   interface PatchRegistry {\n *     \"tilling.till\": { x: number; y: number };\n *   }\n * }\n * ```\n *\n * Payloads must be JSON-serializable: patches are sent over the network, stored\n * and replayed.\n */\nexport interface PatchRegistry {\n  \"element.add\": { readonly element: MapElement; readonly index?: number };\n  \"element.remove\": { readonly id: string };\n  \"element.move\": { readonly id: string; readonly x: number; readonly y: number };\n  /** `kind` replaces the asset reference. `depth: null` and `scale: null` clear them. */\n  \"element.update\": {\n    readonly id: string;\n    readonly set: {\n      readonly kind?: string;\n      readonly depth?: MapDepth | null;\n      readonly scale?: MapScale | null;\n    };\n  };\n  /** Merges `set` into the element data, then removes the `unset` keys. */\n  \"element.data\": { readonly id: string; readonly set?: JsonObject; readonly unset?: readonly string[] };\n  \"event.add\": { readonly event: MapEvent; readonly index?: number };\n  \"event.remove\": { readonly id: string };\n  \"event.move\": { readonly id: string; readonly x: number; readonly y: number };\n  /** Sets the data a feature owns. An absent `value` removes it. */\n  \"extension.set\": { readonly id: string; readonly value?: JsonValue };\n}\n\nexport type PatchType = keyof PatchRegistry & string;\n\nexport type MapPatchOf<K extends PatchType> = {\n  readonly type: K;\n  /**\n   * Revision the patch was computed against. The authority rejects (or rebases)\n   * a patch built on a stale revision.\n   */\n  readonly baseRevision?: number;\n} & PatchRegistry[K];\n\n/** Discriminated union on `type`, derived from the registry. */\nexport type MapPatch = { [K in PatchType]: MapPatchOf<K> }[PatchType];\n\nexport type PatchOutcome =\n  | {\n      readonly ok: true;\n      readonly state: MapState;\n      /** Patches that undo this one, in the order they must be applied. */\n      readonly inverse: readonly MapPatch[];\n    }\n  | { readonly ok: false; readonly rejection: MapRejection };\n\n/** How a patch type changes the state, and how it is undone. Pure: never mutate `state`. */\nexport interface PatchHandler<K extends PatchType> {\n  apply(state: MapState, patch: MapPatchOf<K>): PatchOutcome;\n}\n\nexport type PatchHandlers = { readonly [K in PatchType]?: PatchHandler<K> };\n\nexport const patchOk = (state: MapState, inverse: readonly MapPatch[]): PatchOutcome => ({ ok: true, state, inverse });\n\nexport const patchFail = (code: RejectionCode, message: string): PatchOutcome => ({\n  ok: false,\n  rejection: { code, message },\n});\n\n/** Declares handlers with their types checked against the registry. */\nexport function definePatchHandlers(handlers: PatchHandlers): PatchHandlers {\n  return handlers;\n}\n"],"mappings":";AAyEA,IAAa,WAAW,OAAiB,aAAgD;CAAE,IAAI;CAAM;CAAO;AAAQ;AAEpH,IAAa,aAAa,MAAqB,aAAmC;CAChF,IAAI;CACJ,WAAW;EAAE;EAAM;CAAQ;AAC7B;;AAGA,SAAgB,oBAAoB,UAAwC;CAC1E,OAAO;AACT"}

package/dist/model/result.d.ts

@@ -0,0 +1,22 @@
+import { MapRejection } from './errors';
+import { MapPatch } from './patches';
+export type MaybePromise<T> = T | Promise<T>;
+export type Unsubscribe = () => void;
+export interface ApplySuccess {
+    readonly ok: true;
+    /** Revision of the map after the change. A batch gets a single revision. */
+    readonly revision: number;
+    /** Patches that were applied. */
+    readonly patches: readonly MapPatch[];
+    /** Patches that undo the change, in the order they must be applied. */
+    readonly inverse: readonly MapPatch[];
+}
+export interface ApplyFailure {
+    readonly ok: false;
+    readonly rejection: MapRejection;
+}
+export type ApplyResult = ApplySuccess | ApplyFailure;
+export declare const isThenable: <T>(value: MaybePromise<T>) => value is Promise<T>;
+/** Runs `next` on a value that may or may not be a promise, keeping sync values sync. */
+export declare function chain<T, U>(value: MaybePromise<T>, next: (value: T) => U): MaybePromise<U>;
+//# sourceMappingURL=result.d.ts.map

package/dist/model/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/model/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CAClC;AAED,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAEtD,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,OAAO,YAAY,CAAC,CAAC,CAAC,KAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CACgC,CAAC;AAE1G,yFAAyF;AACzF,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAE1F"}

package/dist/model/result.js

@@ -0,0 +1,10 @@
+//#region src/model/result.ts
+var isThenable = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+/** Runs `next` on a value that may or may not be a promise, keeping sync values sync. */
+function chain(value, next) {
+	return isThenable(value) ? value.then(next) : next(value);
+}
+//#endregion
+export { chain, isThenable };
+
+//# sourceMappingURL=result.js.map

package/dist/model/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","names":[],"sources":["../../src/model/result.ts"],"sourcesContent":["import type { MapRejection } from \"./errors\";\nimport type { MapPatch } from \"./patches\";\n\nexport type MaybePromise<T> = T | Promise<T>;\nexport type Unsubscribe = () => void;\n\nexport interface ApplySuccess {\n  readonly ok: true;\n  /** Revision of the map after the change. A batch gets a single revision. */\n  readonly revision: number;\n  /** Patches that were applied. */\n  readonly patches: readonly MapPatch[];\n  /** Patches that undo the change, in the order they must be applied. */\n  readonly inverse: readonly MapPatch[];\n}\n\nexport interface ApplyFailure {\n  readonly ok: false;\n  readonly rejection: MapRejection;\n}\n\nexport type ApplyResult = ApplySuccess | ApplyFailure;\n\nexport const isThenable = <T>(value: MaybePromise<T>): value is Promise<T> =>\n  typeof value === \"object\" && value !== null && typeof (value as { then?: unknown }).then === \"function\";\n\n/** Runs `next` on a value that may or may not be a promise, keeping sync values sync. */\nexport function chain<T, U>(value: MaybePromise<T>, next: (value: T) => U): MaybePromise<U> {\n  return isThenable(value) ? value.then(next) : next(value);\n}\n"],"mappings":";AAuBA,IAAa,cAAiB,UAC5B,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAQ,MAA6B,SAAS;;AAG/F,SAAgB,MAAY,OAAwB,MAAwC;CAC1F,OAAO,WAAW,KAAK,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK;AAC1D"}

package/dist/model/source.d.ts

@@ -0,0 +1,52 @@
+import { MapDefinition, MapElement, MapEvent } from './definition';
+export interface MapRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** The part of a map that falls inside a rectangle, for streaming large maps. */
+export interface MapRegion {
+    readonly id: string;
+    readonly rect: MapRect;
+    readonly elements: readonly MapElement[];
+    readonly events: readonly MapEvent[];
+}
+/** Where a map comes from: code, a JSON file, Tiled, a database, Studio… */
+export interface MapSource {
+    load(id: string): Promise<MapDefinition>;
+    /** Natively loads one region. When absent, {@link loadMapRegion} derives it from `load`. */
+    loadRegion?(id: string, rect: MapRect): Promise<MapRegion>;
+    list?(): Promise<readonly string[]>;
+}
+export type MapSourceErrorCode = "not-found" | "load-failed";
+export declare class MapSourceError extends Error {
+    readonly code: MapSourceErrorCode;
+    readonly mapId: string;
+    constructor(code: MapSourceErrorCode, mapId: string, message: string);
+}
+/**
+ * Elements and events whose origin falls in `rect`, grown by `margin` pixels so
+ * that objects larger than their origin are not cut off at the border.
+ */
+export declare function regionOf(definition: MapDefinition, rect: MapRect, margin?: number): MapRegion;
+export declare function loadMapRegion(source: MapSource, id: string, rect: MapRect, margin?: number): Promise<MapRegion>;
+/** Maps written in code (`defineMap`). Every `load` returns a fresh copy. */
+export declare function codeMapSource(maps: readonly MapDefinition[]): MapSource;
+export type JsonMapSourceOptions = {
+    readonly maps: Readonly<Record<string, unknown>>;
+} | {
+    readonly read: (id: string) => unknown | Promise<unknown>;
+};
+/** Maps stored as JSON (files, a database). Content is validated and migrated on load. */
+export declare function jsonMapSource(options: JsonMapSourceOptions): MapSource;
+export interface HttpMapSourceOptions {
+    /** Maps are fetched from `${baseUrl}/${id}`, unless `url` is given. */
+    readonly baseUrl: string;
+    readonly url?: (id: string) => string;
+    readonly fetch?: typeof fetch;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Maps served over HTTP as JSON. The `fetch` implementation can be injected. */
+export declare function httpMapSource(options: HttpMapSourceOptions): MapSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/model/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/model/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAIxE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;CACtC;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzC,4FAA4F;IAC5F,UAAU,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,CAAC;AAE7D,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMrE;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,SAAS,CAOxF;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAGhH;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAYvE;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC;AAElE,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAgBtE;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAatE"}

package/dist/model/source.js

@@ -0,0 +1,75 @@
+import { cloneJson } from "./json.js";
+import { parseMapDefinition } from "./parse.js";
+//#region src/model/source.ts
+var MapSourceError = class extends Error {
+	code;
+	mapId;
+	constructor(code, mapId, message) {
+		super(message);
+		this.name = "MapSourceError";
+		this.code = code;
+		this.mapId = mapId;
+	}
+};
+var inside = (x, y, rect, margin) => x >= rect.x - margin && x <= rect.x + rect.width + margin && y >= rect.y - margin && y <= rect.y + rect.height + margin;
+/**
+* Elements and events whose origin falls in `rect`, grown by `margin` pixels so
+* that objects larger than their origin are not cut off at the border.
+*/
+function regionOf(definition, rect, margin = 0) {
+	return {
+		id: definition.id,
+		rect,
+		elements: definition.elements.filter((element) => inside(element.x, element.y, rect, margin)),
+		events: definition.events.filter((entry) => inside(entry.x, entry.y, rect, margin))
+	};
+}
+async function loadMapRegion(source, id, rect, margin = 0) {
+	if (source.loadRegion) return source.loadRegion(id, rect);
+	return regionOf(await source.load(id), rect, margin);
+}
+/** Maps written in code (`defineMap`). Every `load` returns a fresh copy. */
+function codeMapSource(maps) {
+	const table = new Map(maps.map((map) => [map.id, map]));
+	return {
+		async load(id) {
+			const map = table.get(id);
+			if (!map) throw new MapSourceError("not-found", id, `Unknown map "${id}"`);
+			return cloneJson(map);
+		},
+		async list() {
+			return [...table.keys()];
+		}
+	};
+}
+/** Maps stored as JSON (files, a database). Content is validated and migrated on load. */
+function jsonMapSource(options) {
+	return {
+		async load(id) {
+			let raw;
+			if ("maps" in options) {
+				if (!Object.hasOwn(options.maps, id)) throw new MapSourceError("not-found", id, `Unknown map "${id}"`);
+				raw = options.maps[id];
+			} else raw = await options.read(id);
+			return parseMapDefinition(raw);
+		},
+		async list() {
+			return "maps" in options ? Object.keys(options.maps) : [];
+		}
+	};
+}
+/** Maps served over HTTP as JSON. The `fetch` implementation can be injected. */
+function httpMapSource(options) {
+	const doFetch = options.fetch ?? ((...args) => fetch(...args));
+	const urlOf = options.url ?? ((id) => `${options.baseUrl.replace(/\/$/, "")}/${encodeURIComponent(id)}`);
+	return jsonMapSource({ async read(id) {
+		const response = await doFetch(urlOf(id), options.headers ? { headers: { ...options.headers } } : void 0);
+		if (response.status === 404) throw new MapSourceError("not-found", id, `Unknown map "${id}"`);
+		if (!response.ok) throw new MapSourceError("load-failed", id, `Loading map "${id}" failed with status ${response.status}`);
+		return response.json();
+	} });
+}
+//#endregion
+export { MapSourceError, codeMapSource, httpMapSource, jsonMapSource, loadMapRegion, regionOf };
+
+//# sourceMappingURL=source.js.map

package/dist/model/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","names":[],"sources":["../../src/model/source.ts"],"sourcesContent":["import type { MapDefinition, MapElement, MapEvent } from \"./definition\";\nimport { cloneJson, type JsonValue } from \"./json\";\nimport { parseMapDefinition } from \"./parse\";\n\nexport interface MapRect {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n}\n\n/** The part of a map that falls inside a rectangle, for streaming large maps. */\nexport interface MapRegion {\n  readonly id: string;\n  readonly rect: MapRect;\n  readonly elements: readonly MapElement[];\n  readonly events: readonly MapEvent[];\n}\n\n/** Where a map comes from: code, a JSON file, Tiled, a database, Studio… */\nexport interface MapSource {\n  load(id: string): Promise<MapDefinition>;\n  /** Natively loads one region. When absent, {@link loadMapRegion} derives it from `load`. */\n  loadRegion?(id: string, rect: MapRect): Promise<MapRegion>;\n  list?(): Promise<readonly string[]>;\n}\n\nexport type MapSourceErrorCode = \"not-found\" | \"load-failed\";\n\nexport class MapSourceError extends Error {\n  readonly code: MapSourceErrorCode;\n  readonly mapId: string;\n\n  constructor(code: MapSourceErrorCode, mapId: string, message: string) {\n    super(message);\n    this.name = \"MapSourceError\";\n    this.code = code;\n    this.mapId = mapId;\n  }\n}\n\nconst inside = (x: number, y: number, rect: MapRect, margin: number): boolean =>\n  x >= rect.x - margin && x <= rect.x + rect.width + margin && y >= rect.y - margin && y <= rect.y + rect.height + margin;\n\n/**\n * Elements and events whose origin falls in `rect`, grown by `margin` pixels so\n * that objects larger than their origin are not cut off at the border.\n */\nexport function regionOf(definition: MapDefinition, rect: MapRect, margin = 0): MapRegion {\n  return {\n    id: definition.id,\n    rect,\n    elements: definition.elements.filter((element) => inside(element.x, element.y, rect, margin)),\n    events: definition.events.filter((entry) => inside(entry.x, entry.y, rect, margin)),\n  };\n}\n\nexport async function loadMapRegion(source: MapSource, id: string, rect: MapRect, margin = 0): Promise<MapRegion> {\n  if (source.loadRegion) return source.loadRegion(id, rect);\n  return regionOf(await source.load(id), rect, margin);\n}\n\n/** Maps written in code (`defineMap`). Every `load` returns a fresh copy. */\nexport function codeMapSource(maps: readonly MapDefinition[]): MapSource {\n  const table = new Map(maps.map((map) => [map.id, map]));\n  return {\n    async load(id) {\n      const map = table.get(id);\n      if (!map) throw new MapSourceError(\"not-found\", id, `Unknown map \"${id}\"`);\n      return cloneJson(map as unknown as JsonValue) as unknown as MapDefinition;\n    },\n    async list() {\n      return [...table.keys()];\n    },\n  };\n}\n\nexport type JsonMapSourceOptions =\n  | { readonly maps: Readonly<Record<string, unknown>> }\n  | { readonly read: (id: string) => unknown | Promise<unknown> };\n\n/** Maps stored as JSON (files, a database). Content is validated and migrated on load. */\nexport function jsonMapSource(options: JsonMapSourceOptions): MapSource {\n  return {\n    async load(id) {\n      let raw: unknown;\n      if (\"maps\" in options) {\n        if (!Object.hasOwn(options.maps, id)) throw new MapSourceError(\"not-found\", id, `Unknown map \"${id}\"`);\n        raw = options.maps[id];\n      } else {\n        raw = await options.read(id);\n      }\n      return parseMapDefinition(raw);\n    },\n    async list() {\n      return \"maps\" in options ? Object.keys(options.maps) : [];\n    },\n  };\n}\n\nexport interface HttpMapSourceOptions {\n  /** Maps are fetched from `${baseUrl}/${id}`, unless `url` is given. */\n  readonly baseUrl: string;\n  readonly url?: (id: string) => string;\n  readonly fetch?: typeof fetch;\n  readonly headers?: Readonly<Record<string, string>>;\n}\n\n/** Maps served over HTTP as JSON. The `fetch` implementation can be injected. */\nexport function httpMapSource(options: HttpMapSourceOptions): MapSource {\n  const doFetch = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));\n  const urlOf = options.url ?? ((id: string) => `${options.baseUrl.replace(/\\/$/, \"\")}/${encodeURIComponent(id)}`);\n  return jsonMapSource({\n    async read(id) {\n      const response = await doFetch(urlOf(id), options.headers ? { headers: { ...options.headers } } : undefined);\n      if (response.status === 404) throw new MapSourceError(\"not-found\", id, `Unknown map \"${id}\"`);\n      if (!response.ok) {\n        throw new MapSourceError(\"load-failed\", id, `Loading map \"${id}\" failed with status ${response.status}`);\n      }\n      return response.json();\n    },\n  });\n}\n"],"mappings":";;;AA6BA,IAAa,iBAAb,cAAoC,MAAM;CACxC;CACA;CAEA,YAAY,MAA0B,OAAe,SAAiB;EACpE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,QAAQ;CACf;AACF;AAEA,IAAM,UAAU,GAAW,GAAW,MAAe,WACnD,KAAK,KAAK,IAAI,UAAU,KAAK,KAAK,IAAI,KAAK,QAAQ,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,KAAK,IAAI,KAAK,SAAS;;;;;AAMnH,SAAgB,SAAS,YAA2B,MAAe,SAAS,GAAc;CACxF,OAAO;EACL,IAAI,WAAW;EACf;EACA,UAAU,WAAW,SAAS,QAAQ,YAAY,OAAO,QAAQ,GAAG,QAAQ,GAAG,MAAM,MAAM,CAAC;EAC5F,QAAQ,WAAW,OAAO,QAAQ,UAAU,OAAO,MAAM,GAAG,MAAM,GAAG,MAAM,MAAM,CAAC;CACpF;AACF;AAEA,eAAsB,cAAc,QAAmB,IAAY,MAAe,SAAS,GAAuB;CAChH,IAAI,OAAO,YAAY,OAAO,OAAO,WAAW,IAAI,IAAI;CACxD,OAAO,SAAS,MAAM,OAAO,KAAK,EAAE,GAAG,MAAM,MAAM;AACrD;;AAGA,SAAgB,cAAc,MAA2C;CACvE,MAAM,QAAQ,IAAI,IAAI,KAAK,KAAK,QAAQ,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;CACtD,OAAO;EACL,MAAM,KAAK,IAAI;GACb,MAAM,MAAM,MAAM,IAAI,EAAE;GACxB,IAAI,CAAC,KAAK,MAAM,IAAI,eAAe,aAAa,IAAI,gBAAgB,GAAG,EAAE;GACzE,OAAO,UAAU,GAA2B;EAC9C;EACA,MAAM,OAAO;GACX,OAAO,CAAC,GAAG,MAAM,KAAK,CAAC;EACzB;CACF;AACF;;AAOA,SAAgB,cAAc,SAA0C;CACtE,OAAO;EACL,MAAM,KAAK,IAAI;GACb,IAAI;GACJ,IAAI,UAAU,SAAS;IACrB,IAAI,CAAC,OAAO,OAAO,QAAQ,MAAM,EAAE,GAAG,MAAM,IAAI,eAAe,aAAa,IAAI,gBAAgB,GAAG,EAAE;IACrG,MAAM,QAAQ,KAAK;GACrB,OACE,MAAM,MAAM,QAAQ,KAAK,EAAE;GAE7B,OAAO,mBAAmB,GAAG;EAC/B;EACA,MAAM,OAAO;GACX,OAAO,UAAU,UAAU,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC;EAC1D;CACF;AACF;;AAWA,SAAgB,cAAc,SAA0C;CACtE,MAAM,UAAU,QAAQ,WAAW,GAAG,SAAmC,MAAM,GAAG,IAAI;CACtF,MAAM,QAAQ,QAAQ,SAAS,OAAe,GAAG,QAAQ,QAAQ,QAAQ,OAAO,EAAE,EAAE,GAAG,mBAAmB,EAAE;CAC5G,OAAO,cAAc,EACnB,MAAM,KAAK,IAAI;EACb,MAAM,WAAW,MAAM,QAAQ,MAAM,EAAE,GAAG,QAAQ,UAAU,EAAE,SAAS,EAAE,GAAG,QAAQ,QAAQ,EAAE,IAAI,KAAA,CAAS;EAC3G,IAAI,SAAS,WAAW,KAAK,MAAM,IAAI,eAAe,aAAa,IAAI,gBAAgB,GAAG,EAAE;EAC5F,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,eAAe,eAAe,IAAI,gBAAgB,GAAG,uBAAuB,SAAS,QAAQ;EAEzG,OAAO,SAAS,KAAK;CACvB,EACF,CAAC;AACH"}

package/dist/protocol/index.d.ts

@@ -0,0 +1,92 @@
+import { MapDefinition } from '../model/definition';
+import { MapPatch } from '../model/patches';
+import { MapIntent } from '../interaction/intents';
+/**
+ * Messages between a map client and the authority of that map. They are plain JSON, so
+ * any transport carries them: a WebSocket, an RPGJS socket event, a Worker message.
+ *
+ * The client asks (`intent`), the authority decides and tells everybody (`patches`).
+ * A client never sends patches unless the authority trusts it.
+ */
+export declare const MAP_BUILDER_EVENT = "map-builder";
+export type ClientMessage = 
+/** Join, or catch up. `since` is the last revision the client has. */
+{
+    readonly type: "sync";
+    readonly since?: number;
+}
+/** Ask for something to happen. `id` comes back in the answer. */
+ | {
+    readonly type: "intent";
+    readonly id: string;
+    readonly intents: readonly MapIntent[];
+}
+/** Ask for patches to be applied as they are. Only for clients the authority trusts (an editor, an undo). */
+ | {
+    readonly type: "patches";
+    readonly id: string;
+    readonly patches: readonly MapPatch[];
+};
+export type ServerMessage = 
+/** The whole map, at a revision: to join, or when the client is too far behind. */
+{
+    readonly type: "snapshot";
+    readonly revision: number;
+    readonly definition: MapDefinition;
+}
+/** A change that became true. `requestId` is set for the client that asked for it. */
+ | {
+    readonly type: "patches";
+    readonly revision: number;
+    readonly patches: readonly MapPatch[];
+    readonly requestId?: string;
+    /** Who made the change, when the authority knows and wants to say. */
+    readonly author?: string;
+}
+/** The authority said no, and why. */
+ | {
+    readonly type: "rejected";
+    readonly id: string;
+    readonly reason: string;
+    readonly message: string;
+    readonly patchIndex?: number;
+}
+/** The client is up to date: nothing to send. */
+ | {
+    readonly type: "synced";
+    readonly revision: number;
+}
+/** A short visual effect: it is shown, not kept. */
+ | {
+    readonly type: "effect";
+    readonly target: EffectTargetMessage;
+    readonly name: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+export type EffectTargetMessage = string | {
+    readonly type: "element" | "event";
+    readonly id: string;
+};
+/** What an authority refuses to read, to keep a client from making it work too hard. */
+export declare const PROTOCOL_LIMITS: {
+    /** Intents in one request. */
+    readonly maxIntents: 64;
+    /** Patches in one trusted request. */
+    readonly maxPatches: 256;
+    /** Length of a request id. */
+    readonly maxIdLength: 64;
+};
+/**
+ * Reads a message that came from the network. Anything that does not have exactly
+ * the expected shape is `undefined`: never trust a client, nor assume a message is one.
+ */
+export declare function parseClientMessage(raw: unknown): ClientMessage | undefined;
+/** Reads a message the authority sent. A client must not crash on garbage either. */
+export declare function parseServerMessage(raw: unknown): ServerMessage | undefined;
+/** A way to carry messages, whatever the framework: both ends of a connection implement it. */
+export interface MapTransport {
+    send(message: ClientMessage): void;
+    /** Called for every message from the authority. Returns the function that stops listening. */
+    onMessage(listener: (message: ServerMessage) => void): () => void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"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"}