@onlyworlds/sdk 4.9.0 → 4.11.0

package/AGENTS.md

@@ -40,6 +40,15 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Images: `uploadImage(bytes)` returns `{ url, ... }`; set `url` as `image_url`. The bytes go
   to the edge with a single-use ticket from keel, never with the API key. `removeImage(urlOrKey)`
   takes one back (its uploader or the world's owner); it leaves `image_url` on elements as is.
+- Lookup without a model (since 4.11.0): `buildWorldIndex(elements)` then
+  `lookupWorld(index, question)` ranks the elements a question is about (names, then kind, one
+  link step, then text); `renderElement(el, index)` is a compact card with links by name.
+- Photos (browser only, since 4.11.0): `preparePhoto(blob)` shrinks to 2048 px and converts to
+  webp (JPEG where webp can't be encoded) before `uploadImage`.
+- World files (no account needed; since 4.10.0): `readWorldFile(bytes)` opens a `.zip` holding one
+  world folder and returns `{ worldId, name, world, files: [{ path, data }] }`;
+  `writeWorldFile(files, topDir)` makes one. Refusals throw `OwWorldFileError` with a `reason`.
+  `world.json`'s `api` block (link and key) is removed both ways.
 - Ids: the client mints **UUIDv7** on an id-less `create` (since 4.2.0; keel mints v7 too).
   A v4 or v7 id you supply is accepted. **Never sort elements by id**: worlds mix v7, v4
   and legacy `06x…` ids (nibble 7 too, but seconds-first). For creation order use

package/CHANGELOG.md

@@ -5,6 +5,53 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.11.0] — 2026-10-12
+
+### Added
+- **World lookup.** `buildWorldIndex(elements)`, `lookupWorld(index, question, { limit })` and
+  `renderElement(element, index)` find the elements a plain-language question is about, in a
+  world held in memory: no model, no network, a few milliseconds. Ranking: names and short
+  forms first, then name words, supertype and subtype, one link step in both directions, then
+  other text and numbers (always below any name hit). Each hit says why it matched.
+  `renderElement` gives a compact text card with links by name, which is what a model reads
+  when one phrases the answer. Measured on two real worlds (Assembly's Lantern Ask trial):
+  the answer was in the first three results for 60 of 60 questions that name their subject
+  and 17 of 24 held-out questions that only describe it; this code returns the same top 8
+  as the trial's on all 100 questions. Names in any script are matched (Chinese and Japanese
+  only where spaces or punctuation separate the words: there is no word splitting). The question words
+  that steer the link step ("where", "rules", "allies") are English.
+- **Photo preparation.** `preparePhoto(blob, { maxSide, quality, maxBytes })` shrinks and
+  converts a picture in the browser before `uploadImage`: longest side 2048 by default, webp at
+  quality 0.82, from the upload page's converter. A browser that cannot encode webp returns a
+  PNG when asked; the result's real type is checked, and a photo then falls back to JPEG while a
+  PNG stays PNG. When re-encoding would only make a file bigger, the original is kept.
+  `planPhoto` is the pure part (sizes and type order). Walked in Chromium, WebKit and Firefox
+  (a 4032×3024 photo became a 2048-wide webp of about 0.5 MB) and with webp encoding forced off.
+  Needs a browser; in Node it throws a `TypeError` that says so. `PHOTO_TYPES`,
+  `PHOTO_MAX_BYTES` are keel's accepted types and its 15 MB limit.
+
+## [4.10.0] — 2026-10-11
+
+### Added
+- **World files.** `readWorldFile(bytes, { maxBytes, maxEntries, skip })` opens a `.zip` that
+  holds one world folder (Folder Format §4.1, a portable copy) and returns
+  `{ worldId, name, world, files }`; `writeWorldFile(files, topDir)` makes one. Bytes in,
+  bytes out: no DOM or file system, so it runs in the browser and in Node. Absorbed from
+  Atlas's reader (Temper's), so Atlas, Lantern and scripts open one file the same way.
+  The reader refuses before returning anything, with **`OwWorldFileError`** and a `reason`:
+  `unsafe_path` (climbs out, absolute, a drive, a backslash, an empty part, a path that is
+  both a file and a folder), `too_big` / `too_many` (1 GiB and 200,000 files uncompressed,
+  `WORLD_FILE_MAX_BYTES` / `WORLD_FILE_MAX_ENTRIES`; the inflated bytes are counted again,
+  since a declared size can lie), `not_a_world` (no `world.json`, unreadable, no string
+  `id`), `more_than_one` (two worlds, loose files beside the folder, a nested world.json),
+  `not_openable` (not a zip). Archive junk (`__MACOSX`, `.DS_Store`, `Thumbs.db`) is
+  dropped. `world.json`'s `api` (the link and its key) is removed on read and on write; a
+  `world.json` without one keeps its exact bytes. The writer refuses a `world.json` that will
+  not parse rather than zip it raw. Every world in a real Atlas folder (15, up to 3,832
+  files) round-trips byte for byte.
+- **First runtime dependency**: `fflate` (zip, no dependencies of its own, the one Atlas
+  uses). Tree-shaken away for code that never calls the world-file functions.
+
 ## [4.9.0] — 2026-10-11
 
 ### Added

package/README.md

@@ -99,6 +99,8 @@ const image = await writer.uploadImage(file); // a Blob, File, ArrayBuffer or Ui
 await writer.patch('character', id, { image_url: image.url });
 ```
 
+In a browser, shrink a phone photo first: `const photo = await preparePhoto(file)` gives a webp (or JPEG where the browser can't encode webp) of at most 2048 px on its longest side; upload `photo.blob`.
+
 The SDK asks the API for a single-use ticket, then sends the bytes straight to the upload host, which never sees your key. webp, png, jpeg or avif (no SVG or gif), up to 15 MB. Each upload counts toward the world's daily limit and the account's storage. To upload yourself (for a progress bar), call `createMediaTicket()` and POST the bytes to its `upload_url` with `Authorization: Bearer <ticket>`.
 
 ```typescript
@@ -135,6 +137,37 @@ try {
 
 The check is per element and the server never merges. Compare the copy you edited from with `err.current`: when the fields you changed are not the ones that moved, send again with `ifMatch: err.current.change_seq`; when the same field moved on both sides, ask the user which to keep. Without `ifMatch` a write is unconditional, as before.
 
+## Finding things in a world
+
+When you hold a world's elements in memory (from a sync, or a world file), `lookupWorld` finds the ones a plain question is about, with no model and no network:
+
+```typescript
+import { buildWorldIndex, lookupWorld, renderElement } from '@onlyworlds/sdk';
+
+const index = buildWorldIndex(elements);          // once per world; each element needs id and type
+const hits = lookupWorld(index, 'who runs the mill in Ostvik?');
+hits[0].element; hits[0].reasons;                 // best first, with why each matched
+renderElement(hits[0].element, index);            // a short text card, links by name
+```
+
+Names come first, then supertype and subtype, then one link step in either direction, then the elements' other text. To have a model phrase an answer, give it the cards of the top hits and ask it to answer only from them.
+
+## World files
+
+A world file is one `.zip` holding a whole world folder (`world.json` and `elements/<type>/*.json`, as Atlas keeps a world on disk), the way Atlas downloads and opens one. It needs no account and works in the browser and in Node.
+
+```typescript
+import { readWorldFile, writeWorldFile, OwWorldFileError } from '@onlyworlds/sdk';
+
+const world = readWorldFile(bytes);   // a Uint8Array
+world.worldId; world.name; world.world; // world.json, parsed
+world.files;                            // [{ path, data }], relative to the world's folder, sorted
+
+const zip = writeWorldFile(world.files, 'hollow-reach-0192a000'); // one top-level folder
+```
+
+The reader refuses a file before returning anything: a path that could land outside the folder, more than 1 GiB or 200,000 files uncompressed (`maxBytes`, `maxEntries` to change them), no `world.json` with an `id`, or more than one world. Check `err.reason` on the `OwWorldFileError` it throws. The world's OnlyWorlds link and key (`world.json`'s `api`) never travel: both functions remove them. A tool's own folder (`.atlas/` and the like) comes back like any other file; pass `skip: path => …` to leave files out.
+
 ## Errors
 
 Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case. A write sent with `ifMatch` that found the element moved throws `OwPreconditionFailedError` (412, `err.isPreconditionFailed`), an `OwApiError` that also carries `current`.

package/dist/index.d.ts

@@ -2459,6 +2459,272 @@ declare function getElementIcon(type: string): string;
 /** Plural display label for an element type (e.g. phenomenon → "Phenomena"). */
 declare function getElementLabel(elementType: ElementType): string;
 
+/**
+ * The world file: one `.zip` holding one whole world as a portable copy
+ * (Folder Format spec §4.1, "a portable copy"), and the reader that opens one
+ * back. Absorbed from Atlas's `src/store/world-file.ts` (Temper's, Atlas
+ * 1.17), so Atlas, Lantern and any script read one file the same way.
+ *
+ * THE FILE: one top-level folder holding every file of the world as it sits
+ * on disk, except the OnlyWorlds link and its key (`world.json` without `api`).
+ * JSON is deflated, everything else stored. A world.json at the root, with no
+ * folder, reads the same.
+ *
+ * THE READER takes bytes and returns bytes: no DOM, `File` or file system, so
+ * it runs in a browser and in Node alike. It refuses, before returning
+ * anything: a path that climbs out, is absolute, names a drive, holds a
+ * backslash or an empty part, or is both a file and a folder; a declared size
+ * or a file count past the budget (and the inflated bytes are counted again,
+ * since a declared size can lie); no world, more than one world, files
+ * outside the world's folder, a world.json nested inside the world; and a
+ * world.json that will not parse or has no string `id`. Archive junk
+ * (`__MACOSX`, `.DS_Store`, `Thumbs.db`) is dropped.
+ *
+ * A tool's own `.<tool>/` folder is the tool's (spec §4): this module knows
+ * none of them. A caller that leaves some of its files out passes `skip`.
+ */
+/** What one world file may hold, uncompressed: Atlas's budget, the writer's and the reader's alike. */
+declare const WORLD_FILE_MAX_BYTES: number;
+declare const WORLD_FILE_MAX_ENTRIES = 200000;
+type OwWorldFileReason = 'unsafe_path' | 'too_big' | 'too_many' | 'not_a_world' | 'more_than_one' | 'not_openable';
+/** A world file was refused; nothing was returned. `reason` says why, for a tool to word its own message. */
+declare class OwWorldFileError extends Error {
+    readonly reason: OwWorldFileReason;
+    constructor(reason: OwWorldFileReason, message?: string);
+}
+interface OwWorldFileEntry {
+    /** Relative to the world's folder, `/`-separated. */
+    path: string;
+    data: Uint8Array;
+}
+interface OwReadWorldFile {
+    worldId: string;
+    /** `world.json`'s `name` as the file has it; `''` when it has none. */
+    name: string;
+    /** `world.json`, parsed, without `api`. */
+    world: Record<string, unknown>;
+    /** The world's files, relative to its folder, `world.json` included (without `api`), sorted by path. */
+    files: OwWorldFileEntry[];
+}
+interface OwReadWorldFileOptions {
+    maxBytes?: number;
+    maxEntries?: number;
+    /** Leave a file out of `files` (a path relative to the world's folder). It still counts against the budget. */
+    skip?: (path: string) => boolean;
+}
+/**
+ * Read a world file. Throws `OwWorldFileError` saying why, having returned
+ * nothing; the caller writes only what this returns.
+ */
+declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions): OwReadWorldFile;
+/**
+ * Write a world file: every file under one top-level folder `topDir`, JSON
+ * deflated, everything else stored, `world.json` without `api`. Refuses
+ * (`OwWorldFileError`) an unsafe path or `topDir`, a duplicate path, and a
+ * world.json that is missing, will not parse (it may hold a key, so it is
+ * never zipped raw) or has no `id`.
+ */
+declare function writeWorldFile(files: OwWorldFileEntry[], topDir: string): Uint8Array;
+
+/**
+ * World lookup: find the elements a plain-language question is about, in a
+ * world held in memory, with no model and no network. Ported from Assembly's
+ * Lantern Ask trial (`dossiers/lantern-ask/lookup.mjs`, round 2), with the
+ * same ranking, so the trial's measurements on two real worlds describe this
+ * code. Pure: runs in a browser and in Node alike.
+ *
+ *   const index = buildWorldIndex(elements);           // API elements or a world folder's files
+ *   const hits  = lookupWorld(index, question);        // ranked, best first, each with its reasons
+ *   const text  = renderElement(hits[0].element, index); // a compact text card, links by name
+ *
+ * Each element needs `id` and `type` (a world folder's files may lack `type`:
+ * set it from the folder name), and usually `name`.
+ *
+ * LINKS: a field is a link when `FIELD_SCHEMA` says so for the element's type,
+ * or when its value is an id-shaped string or an array of them. The second
+ * rule is the trial's own, and it is kept because real data links outside the
+ * schema's names: a world folder's pins and markers carry `map_id` and
+ * `zone_id`, and extension fields (`x_*`) hold references. A link to an id
+ * outside the set is kept as unresolved, so a card can say a link exists.
+ *
+ * RANKING (higher score first; ties: shorter name, then id):
+ *  0. Question and names are normalised: lower case, diacritics stripped,
+ *     possessive 's dropped, "7,875" read as 7875; letters and digits of any
+ *     script are kept, anything else is a space. A content word has 3+
+ *     characters and is no English stopword; a word holding a non-Latin letter
+ *     always counts (a CJK name is often one or two characters). Words are
+ *     split on spaces and punctuation only, so a CJK name is found when the
+ *     question sets it apart that way.
+ *  1. Name phrase: the whole name appears in the question -> 100 + 10 per word.
+ *  2. Alias phrase: a short form appears -> 80 + 10 per word. Short forms: the
+ *     name without a leading "the"; the part before ":" or "("; for characters
+ *     also the part before " of " or "," and the first word.
+ *  3. Name words: question words (3+ letters, not stopwords) equal to a name
+ *     word, or sharing a 5+ letter prefix with it -> 20 + 40 x the
+ *     rarity-weighted share of the name's words matched. Kept only when better
+ *     than 1-2.
+ *  4. Kind: +15 when a question word matches the supertype or subtype (a word
+ *     the name already used does not count again).
+ *  5. One link step from the 12 best direct hits, both directions: a linked-to
+ *     element scores 0.6 x the hit, a linking element 0.45 x; x1.5 when the
+ *     field fits a question word ("where" -> location fields, "rules" ->
+ *     primary_power, ...). Every reason is kept; the best score counts.
+ *  6. Text: question words (and numbers) found in the element's other text and
+ *     number fields add 3 x their summed rarity. An element found only this
+ *     way scores under 19, so below every name hit.
+ *  7. Map furniture (pin, marker, zone, map) x0.85, so a pin never outranks
+ *     its location; it carries no text.
+ */
+/** What the lookup reads from an element: `id`, `type`, `name`, and any other fields. `OwElement` fits. */
+interface OwLookupElement {
+    id: string;
+    type: string;
+    name?: string;
+    [field: string]: unknown;
+}
+/** One link between two elements of the index, by field. */
+interface OwLookupLink {
+    field: string;
+    id: string;
+}
+/**
+ * The index `lookupWorld` and `renderElement` read, built once per world by
+ * `buildWorldIndex`. `byId` is the elements by id; the other tables are the
+ * lookup's working state: read them if useful, but their shape may change.
+ */
+interface OwWorldIndex<T extends OwLookupElement = OwLookupElement> {
+    byId: ReadonlyMap<string, T>;
+    /** Links each element holds to elements in the set. */
+    out: ReadonlyMap<string, readonly OwLookupLink[]>;
+    /** Links pointing at each element, with the holder's id. */
+    inn: ReadonlyMap<string, readonly OwLookupLink[]>;
+    /** Links each element holds to ids not in the set. */
+    unresolved: ReadonlyMap<string, readonly OwLookupLink[]>;
+    phrase: ReadonlyMap<string, readonly {
+        id: string;
+        kind: 'name' | 'alias';
+    }[]>;
+    tokenIds: ReadonlyMap<string, ReadonlySet<string>>;
+    nameWords: ReadonlyMap<string, readonly string[]>;
+    idf: ReadonlyMap<string, number>;
+    textIds: ReadonlyMap<string, ReadonlySet<string>>;
+    textIdf: ReadonlyMap<string, number>;
+}
+/** Why an element matched: by its name or a short form of it, by name words, by other text, or by one link. */
+type OwLookupReason = {
+    kind: 'name' | 'alias' | 'word' | 'text';
+    text: string;
+} | {
+    kind: 'link';
+    dir: 'out' | 'in';
+    field: string;
+    from: string | undefined;
+    fromId: string;
+};
+/** One ranked result. `dir: 'out'` on a link reason: the hit `from` links to this element; `'in'`: this element links to it. */
+interface OwLookupHit<T extends OwLookupElement = OwLookupElement> {
+    element: T;
+    /** Rounded to one decimal; comparable within one lookup only. */
+    score: number;
+    reasons: OwLookupReason[];
+}
+interface OwLookupOptions {
+    /** How many hits to return (default 8). */
+    limit?: number;
+}
+interface OwRenderOptions {
+    /** Description characters kept (default 500). */
+    descMax?: number;
+    /** Linked names listed per field (default 12). */
+    linkMax?: number;
+    /** Incoming names listed per type and field (default 10). */
+    incomingMax?: number;
+}
+/**
+ * Index a world's elements for `lookupWorld` and `renderElement`. Elements
+ * without an `id` are left out; a repeated id keeps the last. Build it once
+ * per world and again after the world changes.
+ */
+declare function buildWorldIndex<T extends OwLookupElement>(elements: Iterable<T>): OwWorldIndex<T>;
+/**
+ * The elements a question is most likely about, best first (`limit`, default
+ * 8). Names rank first, then elements one link away from a named one, then
+ * elements whose other text holds the question's words. An empty question
+ * returns no hits.
+ */
+declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>, question: string, { limit }?: OwLookupOptions): OwLookupHit<T>[];
+/**
+ * A compact text card for one element, for a person or a model: name, type,
+ * kind, description, its fields, its links by name (or how many point outside
+ * the data), and what links to it.
+ */
+declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, { descMax, linkMax, incomingMax }?: OwRenderOptions): string;
+
+/**
+ * Photo preparation: make a picture from a phone's camera or files ready for
+ * `uploadImage` (webp, png, jpeg or avif, at most 15 MB), in the browser,
+ * before it leaves the device. Lifted from the upload page's converter
+ * (upload.onlyworlds.com, Boss's): canvas, webp at quality 0.82, alpha kept.
+ *
+ * Two traps it handles:
+ * - A browser that cannot encode webp hands back a PNG instead (Safari has
+ *   long done this), and a PNG of a photo is huge. The result's real type is
+ *   checked; when webp did not come back, a photo falls back to JPEG at the
+ *   same quality and a PNG source stays PNG (it may have transparency).
+ * - Re-encoding an already compressed file at the same size can make it
+ *   bigger: then the original is kept, if its type is one keel accepts.
+ *
+ * `planPhoto` is the pure part (sizes and types), so it is tested anywhere;
+ * `preparePhoto` needs a browser (`createImageBitmap` and a canvas).
+ */
+/** The picture types keel's image upload accepts. */
+declare const PHOTO_TYPES: readonly ["image/webp", "image/png", "image/jpeg", "image/avif"];
+/** keel's limit for one picture. */
+declare const PHOTO_MAX_BYTES: number;
+interface OwPhotoOptions {
+    /** The longest side in pixels, after shrinking. Default 2048: a notebook page stays readable and a phone upload stays small. */
+    maxSide?: number;
+    /** Encoder quality for webp and jpeg, 0 to 1. Default 0.82 (the media pipeline's q82). */
+    quality?: number;
+    /** Refuse a result over this many bytes. Default 15 MB, keel's limit. */
+    maxBytes?: number;
+}
+interface OwPhotoPlan {
+    width: number;
+    height: number;
+    /** 1 when no shrinking is needed. */
+    scale: number;
+    /** The types to try, in order; the first one the browser really produces wins. */
+    targets: string[];
+}
+interface OwPreparedPhoto {
+    blob: Blob;
+    type: string;
+    width: number;
+    height: number;
+    /** The input, for showing "4032×3024 · 3.1 MB → 2048×1536 webp · 410 KB". */
+    original: {
+        width: number;
+        height: number;
+        type: string;
+        size: number;
+    };
+    /** True when the original bytes were kept unchanged. */
+    kept: boolean;
+}
+/** Sizes and types for one picture: pure, no browser needed. */
+declare function planPhoto(source: {
+    width: number;
+    height: number;
+    type: string;
+}, opts?: OwPhotoOptions): OwPhotoPlan;
+/**
+ * Shrink and convert a picture for upload. Throws `TypeError` outside a
+ * browser, for a file the browser cannot decode, or when the result is still
+ * over `maxBytes`.
+ */
+declare function preparePhoto(input: Blob, opts?: OwPhotoOptions): Promise<OwPreparedPhoto>;
+
 /**
  * OnlyWorlds Token Management API Types
  *
@@ -2743,4 +3009,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwMediaTicket, OwNetworkError, type OwPage, OwPreconditionFailedError, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation };
+export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };

package/dist/index.js

@@ -1333,6 +1333,570 @@ function getElementLabel(elementType) {
   return ELEMENT_LABELS[elementType];
 }
 
+// src/world-file.ts
+import { unzipSync, zipSync } from "fflate";
+var WORLD_FILE = "world.json";
+var WORLD_FILE_MAX_BYTES = 1024 ** 3;
+var WORLD_FILE_MAX_ENTRIES = 2e5;
+var MESSAGES = {
+  unsafe_path: "The world file holds a path that cannot be written safely.",
+  too_big: "The world file is bigger than the budget allows.",
+  too_many: "The world file holds more files than the budget allows.",
+  not_a_world: "The file is not a world: it has no readable world.json with an id.",
+  more_than_one: "The file holds more than one world, or files outside the world's folder.",
+  not_openable: "The file is not a zip that can be read."
+};
+var OwWorldFileError = class extends Error {
+  constructor(reason, message = MESSAGES[reason]) {
+    super(message);
+    this.name = "OwWorldFileError";
+    this.reason = reason;
+  }
+};
+function isSafePath(path) {
+  if (!path || path.includes("\\") || path.startsWith("/") || /^[a-zA-Z]:/.test(path)) return false;
+  return path.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+function isJunk(path) {
+  return path.split("/").some((seg) => seg === "__MACOSX" || seg === ".DS_Store" || seg === "Thumbs.db");
+}
+function parseWorld(data) {
+  let meta;
+  try {
+    meta = JSON.parse(new TextDecoder().decode(data));
+  } catch {
+    throw new OwWorldFileError("not_a_world");
+  }
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) throw new OwWorldFileError("not_a_world");
+  const id = meta.id;
+  if (typeof id !== "string" || !id.trim()) throw new OwWorldFileError("not_a_world");
+  return meta;
+}
+function withoutLink(data, meta) {
+  if (!("api" in meta)) return { data, world: meta };
+  const { api: _link, ...rest } = meta;
+  return { data: new TextEncoder().encode(JSON.stringify(rest, null, 2) + "\n"), world: rest };
+}
+function readWorldFile(bytes, opts = {}) {
+  const maxBytes = opts.maxBytes ?? WORLD_FILE_MAX_BYTES;
+  const maxEntries = opts.maxEntries ?? WORLD_FILE_MAX_ENTRIES;
+  let declared = 0;
+  let count = 0;
+  let refusal = null;
+  let raw;
+  try {
+    raw = unzipSync(bytes, {
+      filter: (file) => {
+        if (refusal) return false;
+        if (file.name.endsWith("/")) return false;
+        if (!isSafePath(file.name)) {
+          refusal = "unsafe_path";
+          return false;
+        }
+        if (isJunk(file.name)) return false;
+        count++;
+        declared += file.originalSize;
+        if (count > maxEntries) {
+          refusal = "too_many";
+          return false;
+        }
+        if (declared > maxBytes) {
+          refusal = "too_big";
+          return false;
+        }
+        return true;
+      }
+    });
+  } catch {
+    throw new OwWorldFileError(refusal ?? "not_openable");
+  }
+  if (refusal) throw new OwWorldFileError(refusal);
+  const names = Object.keys(raw);
+  if (names.reduce((n, k) => n + raw[k].length, 0) > maxBytes) throw new OwWorldFileError("too_big");
+  const nameSet = new Set(names);
+  for (const n of names) {
+    const segs = n.split("/");
+    for (let i = 1; i < segs.length; i++) {
+      if (nameSet.has(segs.slice(0, i).join("/"))) throw new OwWorldFileError("unsafe_path");
+    }
+  }
+  let prefix;
+  if (nameSet.has(WORLD_FILE)) {
+    prefix = "";
+  } else {
+    const tops = new Set(names.map((n) => n.includes("/") ? n.split("/")[0] + "/" : n));
+    const worldTops = [...tops].filter((t) => t.endsWith("/") && nameSet.has(`${t}${WORLD_FILE}`));
+    if (worldTops.length === 0) throw new OwWorldFileError("not_a_world");
+    if (worldTops.length > 1 || tops.size > 1) throw new OwWorldFileError("more_than_one");
+    prefix = worldTops[0];
+  }
+  const worldName = `${prefix}${WORLD_FILE}`;
+  if (names.some((n) => n !== worldName && n.endsWith(`/${WORLD_FILE}`))) throw new OwWorldFileError("more_than_one");
+  const parsed = withoutLink(raw[worldName], parseWorld(raw[worldName]));
+  const files = [];
+  for (const n of names) {
+    const path = n.slice(prefix.length);
+    if (opts.skip?.(path)) continue;
+    files.push({ path, data: n === worldName ? parsed.data : raw[n] });
+  }
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const name = parsed.world.name;
+  return {
+    worldId: parsed.world.id,
+    name: typeof name === "string" ? name : "",
+    world: parsed.world,
+    files
+  };
+}
+function writeWorldFile(files, topDir) {
+  if (!isSafePath(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
+  const input = {};
+  let sawWorld = false;
+  for (const f of files) {
+    if (!isSafePath(f.path)) throw new OwWorldFileError("unsafe_path");
+    const key = `${topDir}/${f.path}`;
+    if (key in input) throw new OwWorldFileError("unsafe_path", `The path ${f.path} is listed twice.`);
+    let data = f.data;
+    if (f.path === WORLD_FILE) {
+      data = withoutLink(data, parseWorld(data)).data;
+      sawWorld = true;
+    }
+    input[key] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0 }];
+  }
+  if (!sawWorld) throw new OwWorldFileError("not_a_world");
+  return zipSync(input);
+}
+
+// src/lookup.ts
+var STOP = new Set("a an the of in on at to for from by with and or is are was were be been who whom whose what which where when why how does do did doesn has have had it its this that these those there their they them he she his her him i me my we our you your about tell know any some all can could would should will not no yes than then so if into out up down over under one two own same other more most much many very just also only s t don isn".split(" "));
+var SPATIAL = /* @__PURE__ */ new Set(["pin", "marker", "zone", "map"]);
+var FIELD_HINTS = {
+  where: ["location", "parent_location", "birthplace", "locations", "estates", "element_id"],
+  live: ["location", "locations", "populations"],
+  lives: ["location", "locations", "populations"],
+  located: ["location", "parent_location"],
+  location: ["location", "parent_location"],
+  born: ["birthplace"],
+  birthplace: ["birthplace"],
+  species: ["species", "parent_species"],
+  race: ["species"],
+  people: ["species", "populations"],
+  rules: ["primary_power", "governs", "operator"],
+  rule: ["primary_power", "governs", "operator"],
+  ruled: ["primary_power", "governs"],
+  holds: ["primary_power", "governs"],
+  realm: ["primary_power"],
+  govern: ["primary_power", "governs"],
+  governs: ["primary_power", "governs"],
+  controls: ["primary_power", "operator"],
+  culture: ["populations"],
+  cultures: ["populations"],
+  folk: ["populations"],
+  ally: ["allies", "friends"],
+  allies: ["allies", "friends"],
+  allied: ["allies"],
+  friends: ["friends"],
+  friend: ["friends"],
+  enemy: ["adversaries", "rivals"],
+  enemies: ["adversaries", "rivals"],
+  rival: ["rivals"],
+  rivals: ["rivals"],
+  fought: ["institutions"],
+  war: ["institutions"],
+  fight: ["institutions"],
+  family: ["family"],
+  house: ["family"],
+  clan: ["family"],
+  member: ["characters", "institutions", "family"],
+  members: ["characters", "institutions", "family"],
+  belong: ["characters", "institutions", "family"],
+  belongs: ["characters", "institutions", "family"],
+  ancestor: ["ancestors"],
+  ancestors: ["ancestors"],
+  region: ["parent_location"],
+  part: ["parent_location", "parent_species"],
+  parent: ["parent_location", "parent_species"]
+};
+var TEXT_SKIP = /* @__PURE__ */ new Set([
+  "id",
+  "name",
+  "type",
+  "image_url",
+  "created_at",
+  "updated_at",
+  "local_updated_at",
+  "server_updated_at",
+  "world",
+  "image_media_id",
+  "element_type"
+]);
+var RENDER_SKIP = /* @__PURE__ */ new Set([
+  "id",
+  "name",
+  "description",
+  "type",
+  "supertype",
+  "subtype",
+  "image_url",
+  "created_at",
+  "updated_at",
+  "local_updated_at",
+  "server_updated_at",
+  "world",
+  "image_media_id"
+]);
+var ID_SHAPE = /^[0-9a-f-]{32,36}$/i;
+var MARKS = new RegExp(`[${String.fromCharCode(768)}-${String.fromCharCode(879)}]`, "g");
+var POSSESSIVE = new RegExp(`['${String.fromCharCode(8217)}]s\\b`, "g");
+function normalize(s) {
+  return String(s ?? "").normalize("NFD").replace(MARKS, "").toLowerCase().replace(POSSESSIVE, "").replace(/(\d),(\d{3})\b/g, "$1$2").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+var words = (s) => s ? s.split(" ") : [];
+var NON_LATIN = /[^\p{Script=Latin}\p{N}]/u;
+var isContent = (w) => w.length >= 3 && !STOP.has(w) || NON_LATIN.test(w);
+var schemaLinks;
+function linkFieldsOf(type) {
+  if (!schemaLinks) {
+    schemaLinks = /* @__PURE__ */ new Map();
+    for (const [t, fields] of Object.entries(FIELD_SCHEMA)) {
+      const s = /* @__PURE__ */ new Set();
+      for (const [f, info] of Object.entries(fields)) if (info.type === "single_link" || info.type === "multi_link") s.add(f);
+      schemaLinks.set(t, s);
+    }
+  }
+  return typeof type === "string" ? schemaLinks.get(type) : void 0;
+}
+function aliasesOf(el) {
+  const raw = String(el.name ?? "");
+  const full = normalize(raw);
+  const out = /* @__PURE__ */ new Set();
+  const add = (s) => {
+    const n = normalize(s);
+    if (n && n !== full && words(n).some(isContent)) out.add(n);
+  };
+  if (/^the\s/i.test(raw)) add(raw.replace(/^the\s+/i, ""));
+  if (/[:(]/.test(raw)) add(raw.split(/[:(]/)[0]);
+  if (el.type === "character") {
+    if (/\sof\s/i.test(raw)) add(raw.split(/\sof\s/i)[0]);
+    if (raw.includes(",")) add(raw.split(",")[0]);
+    const first = words(full)[0];
+    if (first && isContent(first)) add(first);
+  }
+  return [...out];
+}
+function buildWorldIndex(elements) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const el of elements) if (el && el.id) byId.set(el.id, el);
+  const out = /* @__PURE__ */ new Map(), inn = /* @__PURE__ */ new Map();
+  const unresolved = /* @__PURE__ */ new Map();
+  const phrase = /* @__PURE__ */ new Map();
+  const tokenIds = /* @__PURE__ */ new Map();
+  const nameWords = /* @__PURE__ */ new Map();
+  const textIds = /* @__PURE__ */ new Map();
+  const pushTo = (m, k, v) => {
+    if (!m.has(k)) m.set(k, []);
+    m.get(k).push(v);
+  };
+  for (const el of byId.values()) {
+    const schema = linkFieldsOf(el.type);
+    const linkFields = /* @__PURE__ */ new Set();
+    for (const [field, v] of Object.entries(el)) {
+      if (field === "id") continue;
+      const vals = Array.isArray(v) ? v : [v];
+      if (!vals.length) continue;
+      if (schema?.has(field)) {
+        const ids = vals.filter((x) => typeof x === "string" && x !== "");
+        if (!ids.length) continue;
+        linkFields.add(field);
+        for (const id of ids) {
+          if (byId.has(id)) {
+            pushTo(out, el.id, { field, id });
+            pushTo(inn, id, { field, id: el.id });
+          } else pushTo(unresolved, el.id, { field, id });
+        }
+        continue;
+      }
+      if (!vals.every((x) => typeof x === "string" && ID_SHAPE.test(x))) continue;
+      for (const id of vals) {
+        if (byId.has(id)) {
+          pushTo(out, el.id, { field, id });
+          pushTo(inn, id, { field, id: el.id });
+        } else pushTo(unresolved, el.id, { field, id });
+      }
+    }
+    if (!SPATIAL.has(el.type)) {
+      const tw = /* @__PURE__ */ new Set();
+      for (const [field, v] of Object.entries(el)) {
+        if (TEXT_SKIP.has(field) || linkFields.has(field) || field.startsWith("x_") || field.startsWith("atlas_")) continue;
+        const vals = Array.isArray(v) ? v : [v];
+        for (const x of vals) {
+          if (typeof x === "number" && Number.isFinite(x)) tw.add(String(x));
+          else if (typeof x === "string" && x && !ID_SHAPE.test(x)) {
+            for (const w of words(normalize(x))) if (isContent(w) || /^\d+$/.test(w)) tw.add(w);
+          }
+        }
+      }
+      for (const w of tw) {
+        if (!textIds.has(w)) textIds.set(w, /* @__PURE__ */ new Set());
+        textIds.get(w).add(el.id);
+      }
+    }
+    const full = normalize(el.name);
+    if (!full) continue;
+    pushTo(phrase, full, { id: el.id, kind: "name" });
+    for (const a of aliasesOf(el)) pushTo(phrase, a, { id: el.id, kind: "alias" });
+    const cw = [...new Set(words(full).filter(isContent))];
+    nameWords.set(el.id, cw);
+    for (const w of cw) {
+      if (!tokenIds.has(w)) tokenIds.set(w, /* @__PURE__ */ new Set());
+      tokenIds.get(w).add(el.id);
+    }
+  }
+  const N = byId.size || 1;
+  const idf = /* @__PURE__ */ new Map();
+  for (const [w, ids] of tokenIds) idf.set(w, Math.log(1 + N / ids.size));
+  const textIdf = /* @__PURE__ */ new Map();
+  for (const [w, ids] of textIds) textIdf.set(w, Math.log(1 + N / ids.size));
+  return { byId, out, inn, unresolved, phrase, tokenIds, nameWords, idf, textIds, textIdf };
+}
+function similarWords(w, vocab) {
+  const res = [];
+  if (vocab.has(w)) res.push(w);
+  if (w.length >= 5 && !/^\d+$/.test(w)) {
+    for (const t of vocab.keys()) {
+      if (t === w || t.length < 5) continue;
+      const p = Math.min(w.length, t.length);
+      if (p >= 5 && Math.abs(w.length - t.length) <= 3 && (t.startsWith(w) || w.startsWith(t))) res.push(t);
+    }
+  }
+  return res;
+}
+function lookupWorld(index, question, { limit = 8 } = {}) {
+  const seeds = 12;
+  const q = words(normalize(question));
+  const qSet = new Set(q);
+  const cand = /* @__PURE__ */ new Map();
+  const bump = (id, score, reason, direct) => {
+    const c = cand.get(id) || { score: 0, direct: 0, reasons: [] };
+    c.reasons.push(reason);
+    if (score > c.score) c.score = score;
+    if (direct && score > c.direct) c.direct = score;
+    cand.set(id, c);
+  };
+  const qUsed = /* @__PURE__ */ new Map();
+  const useWords = (id, ws) => {
+    if (!qUsed.has(id)) qUsed.set(id, /* @__PURE__ */ new Set());
+    for (const w of ws) qUsed.get(id).add(w);
+  };
+  for (let n = Math.min(8, q.length); n >= 1; n--) {
+    for (let i = 0; i + n <= q.length; i++) {
+      const g = q.slice(i, i + n);
+      if (n === 1 && !isContent(g[0])) continue;
+      const hits = index.phrase.get(g.join(" "));
+      if (!hits) continue;
+      for (const h of hits) {
+        const base = h.kind === "name" ? 100 : 80;
+        bump(h.id, base + 10 * n, { kind: h.kind, text: g.join(" ") }, true);
+        useWords(h.id, g);
+      }
+    }
+  }
+  const matched = /* @__PURE__ */ new Map();
+  for (const w of qSet) {
+    if (!isContent(w)) continue;
+    for (const t of similarWords(w, index.tokenIds)) {
+      for (const id of index.tokenIds.get(t)) {
+        if (!matched.has(id)) matched.set(id, /* @__PURE__ */ new Set());
+        matched.get(id).add(t);
+        useWords(id, [w]);
+      }
+    }
+  }
+  for (const [id, ws] of matched) {
+    const nw = index.nameWords.get(id) || [];
+    const tot = nw.reduce((s, w) => s + index.idf.get(w), 0) || 1;
+    const got = [...ws].reduce((s, w) => s + index.idf.get(w), 0);
+    const score = 20 + 40 * (got / tot);
+    const c = cand.get(id);
+    if (!c || c.direct < score) bump(id, score, { kind: "word", text: [...ws].join(" ") }, true);
+  }
+  const kindBonus = (id) => {
+    const el = index.byId.get(id);
+    const kw = new Set(words(normalize(`${el.supertype ?? ""} ${el.subtype ?? ""}`)).filter(isContent));
+    const used = qUsed.get(id);
+    for (const w of qSet) {
+      if (used?.has(w)) continue;
+      if (kw.has(w) || [...kw].some((k) => k.length >= 5 && w.length >= 5 && (k.startsWith(w) || w.startsWith(k)))) {
+        useWords(id, [w]);
+        return 15;
+      }
+    }
+    return 0;
+  };
+  for (const [id, c] of cand) {
+    const b = kindBonus(id);
+    if (b) {
+      c.score += b;
+      c.direct += b;
+      c.kinded = true;
+    }
+  }
+  const hintFields = /* @__PURE__ */ new Set();
+  for (const w of qSet) for (const f of FIELD_HINTS[w] || []) hintFields.add(f);
+  const seedList = [...cand.entries()].filter(([, c]) => c.direct > 0).sort((a, b) => b[1].direct - a[1].direct).slice(0, seeds);
+  for (const [sid, sc] of seedList) {
+    const sname = index.byId.get(sid).name;
+    for (const { field, id } of index.out.get(sid) || []) {
+      const m = hintFields.has(field) ? 1.5 : 1;
+      bump(id, sc.direct * 0.6 * m, { kind: "link", dir: "out", field, from: sname, fromId: sid }, false);
+    }
+    for (const { field, id } of index.inn.get(sid) || []) {
+      const m = hintFields.has(field) ? 1.5 : 1;
+      bump(id, sc.direct * 0.45 * m, { kind: "link", dir: "in", field, from: sname, fromId: sid }, false);
+    }
+  }
+  for (const [id, c] of cand) {
+    if (!c.kinded) {
+      const b = kindBonus(id);
+      if (b && c.direct === 0) c.score += b;
+    }
+  }
+  const textHits = /* @__PURE__ */ new Map();
+  for (const w of qSet) {
+    if (!isContent(w) && !/^\d+$/.test(w)) continue;
+    for (const t of similarWords(w, index.textIds)) {
+      const f = index.textIdf.get(t);
+      for (const id of index.textIds.get(t)) {
+        if (!textHits.has(id)) textHits.set(id, /* @__PURE__ */ new Map());
+        const m = textHits.get(id);
+        if (!((m.get(w) ?? NaN) >= f)) m.set(w, f);
+      }
+    }
+  }
+  for (const [id, m] of textHits) {
+    const used = qUsed.get(id);
+    const ws = [...m.keys()].filter((w) => !used?.has(w));
+    if (!ws.length) continue;
+    const raw = 3 * ws.reduce((s, w) => s + m.get(w), 0);
+    const reason = { kind: "text", text: ws.join(" ") };
+    const c = cand.get(id);
+    if (c) {
+      c.score += raw;
+      c.reasons.push(reason);
+    } else cand.set(id, { score: 19 * (1 - Math.exp(-raw / 30)), direct: 0, reasons: [reason] });
+  }
+  for (const [id, c] of cand) if (SPATIAL.has(index.byId.get(id).type)) c.score *= 0.85;
+  return [...cand.entries()].map(([id, c]) => ({ element: index.byId.get(id), score: Math.round(c.score * 10) / 10, reasons: c.reasons })).sort((a, b) => b.score - a.score || String(a.element.name).length - String(b.element.name).length || (a.element.id < b.element.id ? -1 : 1)).slice(0, limit);
+}
+function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMax = 10 } = {}) {
+  const el = element;
+  const name = (id) => index.byId.get(id)?.name ?? "?";
+  const kind = [el.supertype, el.subtype].filter((x) => x && x !== "undefined").join(" / ");
+  const lines = [`${el.name} (${el.type}${kind ? `; ${kind}` : ""})`];
+  if (el.description) {
+    const d = String(el.description);
+    lines.push(`description: ${d.length > descMax ? d.slice(0, descMax) + "..." : d}`);
+  }
+  const outBy = /* @__PURE__ */ new Map();
+  for (const { field, id } of index.out.get(el.id) || []) {
+    if (!outBy.has(field)) outBy.set(field, []);
+    outBy.get(field).push(name(id));
+  }
+  const unres = /* @__PURE__ */ new Map();
+  for (const { field } of index.unresolved.get(el.id) || []) unres.set(field, (unres.get(field) || 0) + 1);
+  for (const [field, v] of Object.entries(el)) {
+    if (RENDER_SKIP.has(field) || field.startsWith("x_") || field.startsWith("atlas_")) continue;
+    if (outBy.has(field) || unres.has(field)) {
+      const names = outBy.get(field) || [];
+      let s = names.slice(0, linkMax).join(", ");
+      if (names.length > linkMax) s += ` (+${names.length - linkMax} more)`;
+      const u = unres.get(field);
+      if (u) s += `${s ? "; " : ""}${u} linked element(s) not present in the world data`;
+      lines.push(`${field}: ${s}`);
+      continue;
+    }
+    if (v === null || v === void 0 || v === "" || Array.isArray(v) && !v.length || typeof v === "object" && !Array.isArray(v)) continue;
+    lines.push(`${field}: ${Array.isArray(v) ? v.join(", ") : v}`);
+  }
+  const inBy = /* @__PURE__ */ new Map();
+  for (const { field, id } of index.inn.get(el.id) || []) {
+    const src = index.byId.get(id);
+    if (SPATIAL.has(src.type)) continue;
+    const k = `${src.type}.${field}`;
+    if (!inBy.has(k)) inBy.set(k, []);
+    inBy.get(k).push(src.name);
+  }
+  for (const [k, names] of inBy) {
+    let s = names.slice(0, incomingMax).join(", ");
+    if (names.length > incomingMax) s += ` (+${names.length - incomingMax} more)`;
+    lines.push(`linked from (${k}): ${s}`);
+  }
+  return lines.join("\n");
+}
+
+// src/photo.ts
+var PHOTO_TYPES = ["image/webp", "image/png", "image/jpeg", "image/avif"];
+var PHOTO_MAX_BYTES = 15 * 1024 * 1024;
+function planPhoto(source, opts = {}) {
+  const maxSide = opts.maxSide ?? 2048;
+  if (!(maxSide > 0)) throw new TypeError("preparePhoto: maxSide must be a positive number");
+  if (!(source.width > 0 && source.height > 0)) throw new TypeError("preparePhoto: the picture has no size");
+  const scale = Math.min(1, maxSide / Math.max(source.width, source.height));
+  const width = Math.max(1, Math.round(source.width * scale));
+  const height = Math.max(1, Math.round(source.height * scale));
+  const fallback = source.type === "image/png" ? "image/png" : "image/jpeg";
+  return { width, height, scale, targets: ["image/webp", fallback] };
+}
+function makeCanvas(width, height) {
+  const g = globalThis;
+  if (g.OffscreenCanvas) {
+    const canvas = new g.OffscreenCanvas(width, height);
+    return { canvas, encode: (type, quality) => canvas.convertToBlob({ type, quality }).catch(() => null) };
+  }
+  if (g.document) {
+    const canvas = g.document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    return { canvas, encode: (type, quality) => new Promise((res) => canvas.toBlob(res, type, quality)) };
+  }
+  throw new TypeError("preparePhoto needs a browser: no canvas here");
+}
+async function preparePhoto(input, opts = {}) {
+  const quality = opts.quality ?? 0.82;
+  const maxBytes = opts.maxBytes ?? PHOTO_MAX_BYTES;
+  const decode = globalThis.createImageBitmap;
+  if (!decode) throw new TypeError("preparePhoto needs a browser: no createImageBitmap here");
+  let bitmap;
+  try {
+    bitmap = await decode(input, { imageOrientation: "from-image" });
+  } catch {
+    throw new TypeError("preparePhoto: this browser cannot read that picture");
+  }
+  const original = { width: bitmap.width, height: bitmap.height, type: input.type, size: input.size };
+  try {
+    const plan = planPhoto(original, opts);
+    const { canvas, encode } = makeCanvas(plan.width, plan.height);
+    canvas.getContext("2d").drawImage(bitmap, 0, 0, plan.width, plan.height);
+    let made = null;
+    for (const type of plan.targets) {
+      const b = await encode(type, quality);
+      if (b && b.type === type) {
+        made = b;
+        break;
+      }
+    }
+    if (!made) throw new TypeError("preparePhoto: this browser could not encode the picture");
+    const keepOriginal = plan.scale === 1 && made.size >= input.size && PHOTO_TYPES.includes(input.type);
+    const out = keepOriginal ? { blob: input, type: input.type, width: original.width, height: original.height, kept: true } : { blob: made, type: made.type, width: plan.width, height: plan.height, kept: false };
+    if (out.blob.size > maxBytes) {
+      throw new TypeError(`preparePhoto: still ${Math.ceil(out.blob.size / 1048576)} MB after shrinking; try a smaller maxSide`);
+    }
+    return { ...out, original };
+  } finally {
+    bitmap.close?.();
+  }
+}
+
 // src/token-resource.ts
 var TokenResource = class {
   constructor(client) {
@@ -1518,8 +2082,14 @@ export {
   OwNetworkError,
   OwPreconditionFailedError,
   OwV2Client,
+  OwWorldFileError,
+  PHOTO_MAX_BYTES,
+  PHOTO_TYPES,
   SPATIAL_TYPES,
   TokenResource,
+  WORLD_FILE_MAX_BYTES,
+  WORLD_FILE_MAX_ENTRIES,
+  buildWorldIndex,
   detectKeyKind,
   elementColor,
   errorFromResponse,
@@ -1528,6 +2098,12 @@ export {
   getElementLabel,
   isDemoKey,
   kindCanWrite,
+  lookupWorld,
   parseErrorEnvelope,
-  pinExpectation
+  pinExpectation,
+  planPhoto,
+  preparePhoto,
+  readWorldFile,
+  renderElement,
+  writeWorldFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {
@@ -60,5 +60,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3"
   }
 }