@onlyworlds/sdk 4.10.0 → 4.12.0

package/AGENTS.md

@@ -40,6 +40,14 @@ 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.
+- Invite links (since 4.12.0): `previewJoin(code)` (no credential sent) shows who invites, to
+  which world, in what role; `acceptJoin(code)` with an `ow_a_` account token joins. Bad code:
+  `err.isNotFound`; `err.isAlreadyMember`, `err.isPinRequired` for the two 409s.
+- 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`.

package/CHANGELOG.md

@@ -5,6 +5,46 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.12.0] — 2026-10-12
+
+### Added
+- **Joining a world by link (keel #212).** `previewJoin(code)` reads what a join code holds
+  without using it (`OwJoinPreview`: `reader`, `world`, `invited_by`, `owner_character`,
+  `role`, `with_character`, `expires_at`) and sends no credential, whatever key the client
+  holds. `acceptJoin(code)` accepts an invite link as the account behind the client's `ow_a_`
+  token and returns the new membership (`OwJoinedMembership`, `roster_character` included);
+  a world key is a `TypeError` before anything is sent. New getters on `OwApiError`:
+  `isNotFound` (every bad code is one 404), `isAlreadyMember` and `isPinRequired` (the two
+  409s, told apart by code). Shapes read from keel's code (`accounts/join_api.py`,
+  `accounts/api.py`), since the OpenAPI document gives no response bodies for these routes.
+  Checked live: a bad code on production answers `isNotFound`. A real accept has not been
+  run from here (no account token); Lantern's door is its first live use.
+
+## [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

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
@@ -108,6 +110,17 @@ await writer.patch('character', id, { image_url: null });
 
 The image's uploader or the world's owner can remove an uploaded image; the space goes back to the uploader's storage. Removal leaves elements as they are, so clear their `image_url` yourself (`createRemovalTicket(key).referenced` says how many still show it). A copy the network already holds can keep answering for a while.
 
+## Invite links
+
+A world's owner can invite a person with a link (`https://www.onlyworlds.com/join#ow_j_…`). The code is the part after `#`:
+
+```typescript
+const invite = await client.previewJoin(code);   // who invites, which world, what role; sends no key
+const membership = await account.acceptJoin(code); // account = a client with an ow_a_ token
+```
+
+A bad code (unknown, used, revoked, expired) is one 404 (`err.isNotFound`). Accepting can answer `err.isAlreadyMember` or `err.isPinRequired` (set a PIN first); a refusal never uses up the code.
+
 ## Sync
 
 ```typescript
@@ -135,6 +148,21 @@ 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.

package/dist/index.d.ts

@@ -1988,6 +1988,37 @@ interface OwRemovalTicket {
     referenced: number;
 }
 /** The edge's 200 for one removal. */
+/** POST /join/preview: what a join code holds, read without using it (keel #212). */
+interface OwJoinPreview {
+    /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. */
+    reader: 'person' | 'agent' | (string & {});
+    world: {
+        name: string;
+        description: string | null;
+    };
+    /** The name the inviter signed the link with, or null. */
+    invited_by: string | null;
+    /** The world owner's chosen Character's name, never a username; null when none is set. */
+    owner_character: string | null;
+    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    /** Whether joining gives the joiner a Character of their own (agent links). */
+    with_character: boolean | null;
+    /** ISO 8601, UTC. */
+    expires_at: string;
+    [k: string]: unknown;
+}
+/** POST /account/join: the new membership (the same row as accepting an email invite). */
+interface OwJoinedMembership {
+    /** The membership's id. */
+    id: string;
+    world_id: string;
+    world_name: string;
+    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    joined_at: string | null;
+    /** The id of the joiner's roster Character, or null. */
+    roster_character: string | null;
+    [k: string]: unknown;
+}
 interface OwRemovedImage {
     /** The object key that was removed. */
     removed: string;
@@ -2139,6 +2170,12 @@ declare class OwApiError extends Error {
      * is now, so no second read is needed.
      */
     get isPreconditionFailed(): boolean;
+    /** 404 `not_found`: no such element or route, or a join code that is unknown, used, revoked or expired. */
+    get isNotFound(): boolean;
+    /** acceptJoin: the account is already a member of that world (409 `already_member`). The code is not spent. */
+    get isAlreadyMember(): boolean;
+    /** acceptJoin: the account has no PIN yet, and a member writes with their own (409 `pin_required`). The code is not spent. */
+    get isPinRequired(): boolean;
 }
 /**
  * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
@@ -2368,6 +2405,23 @@ declare class OwV2Client {
     removeImage(keyOrUrl: string, opts?: {
         ticket?: OwRemovalTicket;
     }): Promise<OwRemovedImage>;
+    /**
+     * POST /join/preview -- what a join code holds, without using it: who invites, to
+     * which world, in what role, and `reader` (`person`: accept it with acceptJoin;
+     * `agent`: an AI agent redeems it at POST /join). Sends no credential, whatever key
+     * this client holds. Every bad code (unknown, used, revoked, expired) is the same
+     * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`.
+     */
+    previewJoin(code: string): Promise<OwJoinPreview>;
+    /**
+     * POST /account/join -- accept an invite link's code as the account this client's
+     * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
+     * (every bad code, and a code made for an AI agent), 409 `already_member`
+     * (`err.isAlreadyMember`) and 409 `pin_required` (`err.isPinRequired`: the account
+     * has no PIN yet). A refusal never spends the code. A world key here is a TypeError
+     * before anything is sent.
+     */
+    acceptJoin(code: string): Promise<OwJoinedMembership>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -2526,6 +2580,205 @@ declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions)
  */
 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
  *
@@ -2810,4 +3063,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 OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldMeta, 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, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation, readWorldFile, writeWorldFile };
+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 OwJoinPreview, type OwJoinedMembership, 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

@@ -75,6 +75,18 @@ var OwApiError = class extends Error {
   get isPreconditionFailed() {
     return this.status === 412 && this.code === "precondition_failed";
   }
+  /** 404 `not_found`: no such element or route, or a join code that is unknown, used, revoked or expired. */
+  get isNotFound() {
+    return this.status === 404 && this.code === "not_found";
+  }
+  /** acceptJoin: the account is already a member of that world (409 `already_member`). The code is not spent. */
+  get isAlreadyMember() {
+    return this.status === 409 && this.code === "already_member";
+  }
+  /** acceptJoin: the account has no PIN yet, and a member writes with their own (409 `pin_required`). The code is not spent. */
+  get isPinRequired() {
+    return this.status === 409 && this.code === "pin_required";
+  }
 };
 var OwPreconditionFailedError = class extends OwApiError {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -410,6 +422,31 @@ var OwV2Client = class {
     if (!res.ok) throw await errorFromResponse(res);
     return await res.json();
   }
+  // -- Joining a world by link (keel #212) ----------------------------------
+  /**
+   * POST /join/preview -- what a join code holds, without using it: who invites, to
+   * which world, in what role, and `reader` (`person`: accept it with acceptJoin;
+   * `agent`: an AI agent redeems it at POST /join). Sends no credential, whatever key
+   * this client holds. Every bad code (unknown, used, revoked, expired) is the same
+   * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`.
+   */
+  async previewJoin(code) {
+    return this.request("POST", "/join/preview", { auth: false, body: { code } });
+  }
+  /**
+   * POST /account/join -- accept an invite link's code as the account this client's
+   * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
+   * (every bad code, and a code made for an AI agent), 409 `already_member`
+   * (`err.isAlreadyMember`) and 409 `pin_required` (`err.isPinRequired`: the account
+   * has no PIN yet). A refusal never spends the code. A world key here is a TypeError
+   * before anything is sent.
+   */
+  async acceptJoin(code) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("acceptJoin needs an account token (ow_a_): a world key cannot join a world");
+    }
+    return this.request("POST", "/account/join", { body: { code } });
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0
@@ -1467,6 +1504,436 @@ function writeWorldFile(files, topDir) {
   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) {
@@ -1653,10 +2120,13 @@ export {
   OwPreconditionFailedError,
   OwV2Client,
   OwWorldFileError,
+  PHOTO_MAX_BYTES,
+  PHOTO_TYPES,
   SPATIAL_TYPES,
   TokenResource,
   WORLD_FILE_MAX_BYTES,
   WORLD_FILE_MAX_ENTRIES,
+  buildWorldIndex,
   detectKeyKind,
   elementColor,
   errorFromResponse,
@@ -1665,8 +2135,12 @@ export {
   getElementLabel,
   isDemoKey,
   kindCanWrite,
+  lookupWorld,
   parseErrorEnvelope,
   pinExpectation,
+  planPhoto,
+  preparePhoto,
   readWorldFile,
+  renderElement,
   writeWorldFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {