@onlyworlds/sdk 4.48.1 → 4.50.0

package/AGENTS.md

@@ -79,7 +79,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - 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.
+  `world.json`'s `api` block (link and key) is removed both ways. Both follow Folder Format
+  §4.7 (`.owworld`): the reader checks the central directory before inflating
+  and ignores files beside the world's folder; the writer's output is byte-stable (marker
+  first, UTF-8 name order, 1980 stamps) and holds only `world.json` and the folder's parts.
 - World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
   `atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendarLens` picks
   one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`

package/CHANGELOG.md

@@ -5,6 +5,29 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.50.0] - 2026-10-22
+
+### Added
+
+- `setMyCharacter(characterId | null)`: `PUT /me/character`, a person member's pick of the roster Character that is them in this world (keel PR 160, #533); answers the `/me` body. `err.isCharacterHidden` for the 422 `character_hidden` it and the member PATCH answer.
+- `hidden?: true` on every element body (`OwElementBase`): present only when the owner or a co-builder hid the element and this reader still sees it (keel #537); never on other readers' bodies, ignored in a write.
+- `site` joins `OwWriteDoor`: a write or delete the owner made signed in on onlyworlds.com (keel #530).
+
+## [4.49.0] - 2026-10-22
+
+### Changed
+
+- **The world file follows Folder Format §4.7, the `.owworld` archive** (OW Council #522), and gives the spec's verdict and cause on every one of the 74 fixtures in its conformance set (Quillon's, `owworld-fixtures`), plus its three on-demand floor cases.
+  - The reader parses the central directory itself (zip64 included) and runs every check on names, kinds, methods and sizes before it inflates anything.
+  - Six new refusal causes join `OwWorldFileReason`: `duplicate` (OW-17), `collision` (OW-18: NFC, then simple case folding), `link` (OW-20), `method` (OW-21), `name` (OW-22) and `marker` (OW-6). A `Record<OwWorldFileReason, …>` in a caller needs the six new keys.
+  - The OW-18 fold is the C and S rows of Unicode's CaseFolding.txt 15.1, built in as a table, never the runtime's casing, so a fold a newer Unicode adds stays out until the pin moves (Skeld's ruling, OW Council #9830). `simpleCaseFold(text)` exports it.
+  - Files beside the world's folder are ignored, no longer `more_than_one` (OW-4). A `world.json` under `records/` is a producer's data, not a second world (OW-5). A spanned archive is `not_openable`. An entry that inflates past the size it declares is `too_big` at any budget (OW-14).
+  - The default budget is the spec's floor: `WORLD_FILE_MAX_BYTES` 2 GiB (was 1 GiB), `WORLD_FILE_MAX_ENTRIES` 500,000 (was 200,000) (OW-15).
+  - A `mimetype` marker is never required. One with other bytes than `WORLD_FILE_MEDIA_TYPE` (`application/vnd.onlyworlds.world+zip`, newly exported) is refused, and the marker is never returned as a file.
+  - `files` come back in code point order (the UTF-8 bytes of the name), not UTF-16 order.
+  - The writer gives one set of bytes for one input (OW-12, OW-13). It places the `mimetype` marker first and stored, orders entries by the UTF-8 bytes of their names, and stamps every entry 1980-01-01 00:00 (was the clock).
+  - The writer writes only `world.json`, `elements/`, `spatial/`, `media/`, `records/` and a tool's dot-folder it is handed (OW-7). It leaves out any other file, and a dot-name or `.meta` inside a content folder. It refuses a `name` or a `collision` as the reader would.
+
 ## [4.48.1] - 2026-10-22
 
 ### Changed

package/README.md

@@ -240,19 +240,34 @@ const { token_rating, tokens_remaining, resets_at } = await account.allowance();
 
 ## 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.
+A world file (`.owworld`, a `.zip` by another name) is one archive 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. Both functions follow the Folder Format spec's §4.7 and pass its fixture set.
 
 ```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
+world.files;                            // [{ path, data }], relative to the world's folder, in code point order
 
 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.
+The reader checks every entry before it inflates anything, and refuses the file before returning anything. Check `err.reason` on the `OwWorldFileError` it throws:
+
+| `reason` | what the file holds |
+|---|---|
+| `not_openable` | not a zip, a spanned one, or a broken entry |
+| `unsafe_path` | a path that could land outside the folder, or a path that is both a file and a folder |
+| `name` | a name some disk cannot hold: `CON` and the other device names, a trailing dot or space, `<>:"\|?*`, a control character, a non-ASCII name without the UTF-8 flag |
+| `duplicate`, `collision` | two entries with one name, or two names that differ only in case or in how an accent is written |
+| `link`, `method` | a link or special file, an encrypted entry, or a method other than stored or deflate |
+| `too_big`, `too_many` | more than 2 GiB or 500,000 files uncompressed (`maxBytes`, `maxEntries` to change them), or an entry bigger than it says |
+| `marker` | a `mimetype` entry with other bytes than `WORLD_FILE_MEDIA_TYPE` (a marker is never required) |
+| `not_a_world`, `more_than_one` | no `world.json` with an `id`, two worlds, or a second `world.json` inside the world (one under `records/` is data) |
+
+Files beside the world's folder and archive junk (`__MACOSX`, `.DS_Store`) are ignored. 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.
+
+The writer gives the same bytes for the same files: the `mimetype` marker first, then every entry in the UTF-8 order of its name, stamped 1980-01-01 00:00. It writes `world.json`, `elements/`, `spatial/`, `media/` and `records/`, and leaves any other file out. A tool's dot-folder you hand it travels too, which makes the file a private copy rather than a portable `.owworld`.
 
 ## World calendars
 

package/dist/index.d.ts

@@ -29,8 +29,10 @@ interface OwElementBase {
     created_by?: string | null;
     /** The membership whose write last changed this element (server-managed, read-only); null for the world's owner and for anything last changed before writes recorded it. */
     changed_by?: string | null;
-    /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, or `server` (keel's own writes). The first three are agent-made. Null for anything last changed before writes recorded it. */
-    changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | null;
+    /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, `server` (keel's own writes) or `site` (the owner signed in on onlyworlds.com; keel PR 160). The first three are agent-made. Null for anything last changed before writes recorded it. */
+    changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'site' | null;
+    /** Present, and true, only when the world's owner or a co-builder hid this element and this reader still sees it (server-managed, read-only): the owner, a co-builder, a key the owner minted, or the member who made it; to every other reader the element does not exist. Absent otherwise, whatever `fields` asked; on the read, the list, the change feed's upserts and MCP, never in the download, world sync or v1. Sent in a write it is ignored. */
+    hidden?: true;
     /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq, and the fields its type lists in PUBLIC_FIELDS with their values; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
     known_of?: true;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
@@ -2920,6 +2922,11 @@ declare class OwApiError extends Error {
      * previewJoin, whose `characters` mark each `taken`. The code is not spent.
      */
     get isCharacterTaken(): boolean;
+    /**
+     * setMyCharacter, or the member PATCH's `character` (keel #421, PR 160): the picked Character is
+     * hidden (422 `character_hidden`, `param` character). Unhide it first, or pick another.
+     */
+    get isCharacterHidden(): boolean;
     /**
      * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
      * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
@@ -3148,6 +3155,14 @@ declare class OwV2Client {
      * creates; null for the owner) and the member's Character. A world key's call; an account
      * token is a TypeError before sending.
      */
+    /**
+     * PUT /me/character -- pick the roster Character that is you in this world, or none (keel PR 160,
+     * #533). A person member's write key with its PIN; answers GET /me's body. 422 for a hidden
+     * Character (`character_hidden`, `err.isCharacterHidden`), a guest's pick it did not make, or a
+     * taken Character (`character_taken`); 404 for one this key cannot see; 403 for an agent seat, a
+     * player, the owner (who sets it on the world page) or a read key. A guest's view resets once.
+     */
+    setMyCharacter(character: string | null): Promise<OwMe>;
     me(): Promise<OwMe>;
     /**
      * GET /members -- the world's roster: each member's id (null for the owner), kind, role,
@@ -3842,33 +3857,52 @@ declare function getElementIcon(type: string): string;
 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 world file, `.owworld` (Folder Format spec §4.7; a `.zip` by another
+ * name): one archive holding one whole world as a portable copy (§4.1), 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; brought to §4.7's checks OW-1 to OW-22
+ * and their fixture set (OW Council #522).
  *
  * 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.
+ * it runs in a browser and in Node alike. It reads the central directory
+ * itself (zip64 included) and runs every check on names, kinds, methods and
+ * sizes before it inflates anything. Each refusal names one cause
+ * (`OwWorldFileReason`), checked in the reference checker's order:
+ * - `not_openable`: not a zip, a spanned one, a broken entry or CRC.
+ * - `unsafe_path` (OW-16, OW-19): a name that is not a plain relative path
+ *   (`\`, an empty, `.` or `..` segment, absolute, a drive), or a path that is
+ *   both a file and a folder.
+ * - `link` (OW-20): a Unix mode that is not a regular file or a directory.
+ * - `method` (OW-21): encrypted, or a method other than stored or deflate.
+ * - `name` (OW-22): a Windows device name, a trailing dot or space, one of
+ *   `<>:"|?*` or a control character, a non-ASCII name without the UTF-8 flag.
+ * - `duplicate` (OW-17), `collision` (OW-18: NFC, then simple case folding).
+ * - `too_many`, `too_big` (OW-14, OW-15): past the budget by count or declared
+ *   size, or an entry that inflates past the size it declares.
+ * - `marker` (OW-6): a root `mimetype` entry with other bytes than the media
+ *   type. A marker is never required.
+ * - `not_a_world`, `more_than_one` (OW-2, OW-3, OW-5): no world, two worlds, a
+ *   second `world.json` inside the world (one under `records/` is a
+ *   producer's data), a `world.json` that will not parse or has no string id.
+ * Files beside the world's folder and archive junk (`__MACOSX`, `.DS_Store`,
+ * `Thumbs.db`) are ignored (OW-4), still checked and counted.
+ *
+ * THE WRITER emits a portable copy (OW-7, OW-12, OW-13): the `mimetype` marker
+ * first and stored, then only the folder's parts, every entry stamped
+ * 1980-01-01 00:00, in the UTF-8 byte order of its name, JSON deflated and
+ * everything else stored.
  *
- * 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`.
+ * A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
+ * it like any file (a caller leaves files out with `skip`), and the writer
+ * carries one it is handed, which makes the file a private copy (OW-7, OW-9).
  */
-/** What one world file may hold, uncompressed: Atlas's budget, the writer's and the reader's alike. */
+/** The `mimetype` marker's exact bytes (spec §4.7, OW-6): ASCII, no newline. */
+declare const WORLD_FILE_MEDIA_TYPE = "application/vnd.onlyworlds.world+zip";
+/** The budget, uncompressed: the floor every reader accepts (spec §4.7, OW-15). */
 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';
+declare const WORLD_FILE_MAX_ENTRIES = 500000;
+type OwWorldFileReason = 'unsafe_path' | 'too_big' | 'too_many' | 'not_a_world' | 'more_than_one' | 'not_openable' | 'duplicate' | 'collision' | 'link' | 'method' | 'name' | 'marker';
 /** 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;
@@ -3885,26 +3919,37 @@ interface OwReadWorldFile {
     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. */
+    /** The world's files, relative to its folder, `world.json` included (without `api`), in code point order. */
     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. */
+    /** Leave a file out of `files` (a path relative to the world's folder). It is still checked and counted. */
     skip?: (path: string) => boolean;
 }
+/**
+ * Simple case folding (Unicode 15.1, CaseFolding.txt C and S), code point by
+ * code point: what OW-18 applies after NFC. A code point the table does not
+ * map folds to itself.
+ */
+declare function simpleCaseFold(text: string): string;
 /**
  * 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`.
+ * Write a world file under one top-level folder `topDir`: the `mimetype`
+ * marker first and stored, then `world.json` (without `api`) and the folder's
+ * parts, in UTF-8 byte order, every entry stamped 1980-01-01 00:00, JSON
+ * deflated and everything else stored (spec §4.7, OW-6, OW-7, OW-12, OW-13).
+ * Any other file is left out. A tool's dot-folder in `files` travels, and
+ * makes the result a private copy, not a portable `.owworld` (OW-7): leave it
+ * out of `files` for a portable one. Refuses (`OwWorldFileError`) an unsafe
+ * path or `topDir`, a duplicate path, a name some disk cannot hold, two names
+ * that fold to one, 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;
 
@@ -4717,4 +4762,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -191,6 +191,13 @@ var OwApiError = class extends Error {
   get isCharacterTaken() {
     return this.status === 422 && this.code === "character_taken";
   }
+  /**
+   * setMyCharacter, or the member PATCH's `character` (keel #421, PR 160): the picked Character is
+   * hidden (422 `character_hidden`, `param` character). Unhide it first, or pick another.
+   */
+  get isCharacterHidden() {
+    return this.status === 422 && this.code === "character_hidden";
+  }
   /**
    * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
    * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
@@ -533,6 +540,19 @@ var OwV2Client = class {
    * creates; null for the owner) and the member's Character. A world key's call; an account
    * token is a TypeError before sending.
    */
+  /**
+   * PUT /me/character -- pick the roster Character that is you in this world, or none (keel PR 160,
+   * #533). A person member's write key with its PIN; answers GET /me's body. 422 for a hidden
+   * Character (`character_hidden`, `err.isCharacterHidden`), a guest's pick it did not make, or a
+   * taken Character (`character_taken`); 404 for one this key cannot see; 403 for an agent seat, a
+   * player, the owner (who sets it on the world page) or a read key. A guest's view resets once.
+   */
+  async setMyCharacter(character) {
+    if (this.keyKind === "account") {
+      throw new TypeError("setMyCharacter needs a world key: an account token is not a member of one world");
+    }
+    return this.request("PUT", "/me/character", { write: true, body: { character } });
+  }
   async me() {
     if (this.keyKind === "account") {
       throw new TypeError("me needs a world key: an account token is not a member of one world");
@@ -2514,17 +2534,25 @@ function getElementLabel(elementType) {
 }
 
 // src/world-file.ts
-import { unzipSync, zipSync } from "fflate";
+import { Inflate, inflateSync, zipSync } from "fflate";
 var WORLD_FILE = "world.json";
-var WORLD_FILE_MAX_BYTES = 1024 ** 3;
-var WORLD_FILE_MAX_ENTRIES = 2e5;
+var MARKER_NAME = "mimetype";
+var WORLD_FILE_MEDIA_TYPE = "application/vnd.onlyworlds.world+zip";
+var WORLD_FILE_MAX_BYTES = 2 * 1024 ** 3;
+var WORLD_FILE_MAX_ENTRIES = 5e5;
 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_big: "The world file is bigger than the budget allows, or a file in it is bigger than it says.",
   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."
+  more_than_one: "The file holds more than one world.",
+  not_openable: "The file is not a zip that can be read.",
+  duplicate: "The world file holds two entries with the same name.",
+  collision: "The world file holds two names that differ only in case or in how an accent is written.",
+  link: "The world file holds a link or a special file.",
+  method: "The world file holds an encrypted entry, or one compressed other than stored or deflate.",
+  name: "The world file holds a name that some disk cannot hold.",
+  marker: "The world file's mimetype entry is not the OnlyWorlds media type."
 };
 var OwWorldFileError = class extends Error {
   constructor(reason, message = MESSAGES[reason]) {
@@ -2533,13 +2561,228 @@ var OwWorldFileError = class extends Error {
     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 !== "..");
+var refuse = (reason, message) => {
+  throw new OwWorldFileError(reason, message);
+};
+function pathFault(name) {
+  if (name.includes("\\")) return "holds a backslash";
+  if (name.startsWith("/")) return "is absolute";
+  if (/^[A-Za-z]:/.test(name)) return "names a drive";
+  if (name.split("/").some((seg) => seg === "" || seg === "." || seg === "..")) return "has an empty, . or .. segment";
+  return null;
+}
+var RESERVED = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  ...[1, 2, 3, 4, 5, 6, 7, 8, 9].flatMap((i) => [`COM${i}`, `LPT${i}`])
+]);
+var BAD_CHAR = /[<>:"|?*\p{Cc}]/u;
+function nameFault(name) {
+  for (const seg of name.split("/")) {
+    if (BAD_CHAR.test(seg)) return `segment ${JSON.stringify(seg)} holds a reserved or control character`;
+    if (seg.endsWith(".") || seg.endsWith(" ")) return `segment ${JSON.stringify(seg)} ends in a dot or a space`;
+    if (RESERVED.has(seg.split(".")[0].toUpperCase())) return `segment ${JSON.stringify(seg)} is a Windows device name`;
+  }
+  return null;
 }
 function isJunk(path) {
   return path.split("/").some((seg) => seg === "__MACOSX" || seg === ".DS_Store" || seg === "Thumbs.db");
 }
+var FOLD_RUNS = "1t.q..w,51...lj,5c.n..w,60.7..w,74.o.2.1,8i.3.2.1,8p.8.2.1,96.n.2.1,ag...-3d,ah.3.2.1,an...-7g,ap...5u,aq.2.2.1,au...5q,av...1,ax.2..5p,az...1,b2...27,b3...5m,b4...5n,b5...1,b7...5p,b8...5r,ba...5v,bb...5t,bc...1,bg...5v,bh...5x,bj...5y,bk.3.2.1,bq...62,br...1,bt...62,bw...1,by...62,bz...1,c1.2..61,c3.2.2.1,c7...63,c8...1,cc...1,ck...2,cl...1,cn...2,co...1,cq...2,cr.9.2.1,da.9.2.1,dt...2,du.2.2.1,dy...-2p,dz...-1k,e0.k.2.1,f4...-3m,f6.9.2.1,fu...8bv,fv...1,fx...-4j,fy...8bs,g1...1,g3...-5f,g4...1x,g5...1z,g6.5.2.1,n9...38,og.2.2.1,om...1,ov...38,p2...12,p4.3..11,p8...1s,pa.2..1r,pd.h..w,pv.9..w,qq...1,r3...8,r4...-u,r5...-p,r9...-f,ra...-m,rc.c.2.1,s0...-1i,s1...-1c,s4...-1o,s5...-1s,s7...1,s9...-7,sa...1,sd.3..-3m,sg.g..28,sw.w..w,v4.h.2.1,wa.r.2.1,xs...f,xt.7.2.1,y8.1c.2.1,10x.12..1c,3a8.12..5ls,3bb...5ls,3bh...5ls,3y0.6..-8,5mo...-4su,5mp...-4st,5mq...-4sk,5mr.2..-4si,5mt...-4sj,5mu...-4sc,5mv...-4ro,5mw...r7n,5n4.17..-2bk,5od.3..-2bk,5xc.23.2.1,61n...-1m,61q...-5vj,61s.1c.2.1,64o.8..-8,654.6..-8,65k.8..-8,660.8..-8,66g.6..-8,66x.4.2.-8,67c.8..-8,688.8..-8,68o.8..-8,694.8..-8,69k.2..-8,69m.2..-22,69o...-9,69q...-5j9,6a0.4..-2e,6a4...-9,6ab...-5kz,6ag.2..-8,6ai.2..-2s,6ar...-5kj,6aw.2..-8,6ay.2..-34,6b0...-7,6bc.2..-3k,6be.2..-3i,6bg...-9,6jq...-5st,6ju...-6gv,6jv...-6di,6k2...s,6lc.g..g,6mb...1,792.q..q,8ow.1c..1c,8rk...1,8rm...-8af,8rn...-2xy,8ro...-89z,8rr.3.2.1,8rx...-8bg,8ry...-8al,8rz...-8bj,8s0...-8bi,8s2...1,8s5...1,8se.2..-8cf,8sg.1e.2.1,8vf.2.2.1,8vm...1,wu8.n.2.1,ww0.e.2.1,x0i.7.2.1,x0y.v.2.1,x2x.2.2.1,x31...-r9g,x32.5.2.1,x3f...1,x3h...-wmg,x3k.2.2.1,x3q.a.2.1,x4a...-wn8,x4b...-wnj,x4c...-wnf,x4d...-wn5,x4e...-wn8,x4g...-wlu,x4h...-wmi,x4i...-wlx,x4j...ps,x4k.8.2.1,x50...-1c,x51...-wn7,x52...-raw,x53.2.2.1,x5c...1,x5i.2.2.1,x6d...1,xv4.28..-tzk,1dl1...1,1ee9.q..w,1fcw.14..14,1fhs.10..14,1fn4.b..13,1fng.f..13,1fnw.7..13,1fo4.2..13,1h1c.1f..1s,1jfk.w..w,20cg.w..w,2olc.y..y";
+var foldTable = null;
+function simpleCaseFold(text) {
+  if (!foldTable) {
+    foldTable = /* @__PURE__ */ new Map();
+    for (const run of FOLD_RUNS.split(",")) {
+      const [start, count, stride, delta] = run.split(".");
+      const s = parseInt(start, 36);
+      const n = count ? parseInt(count, 36) : 1;
+      const step = stride ? parseInt(stride, 36) : 1;
+      const d = parseInt(delta, 36);
+      for (let k = 0; k < n; k++) foldTable.set(s + k * step, s + k * step + d);
+    }
+  }
+  let out = "";
+  for (const c of text) {
+    const to = foldTable.get(c.codePointAt(0));
+    out += to === void 0 ? c : String.fromCodePoint(to);
+  }
+  return out;
+}
+function foldName(name) {
+  return simpleCaseFold(name.normalize("NFC"));
+}
+function byCodePoint(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a.codePointAt(i);
+    const y = b.codePointAt(i);
+    if (x !== y) return x - y;
+    if (x > 65535) i++;
+  }
+  return a.length - b.length;
+}
+var u16 = (b, o) => b[o] | b[o + 1] << 8;
+var u32 = (b, o) => (b[o] | b[o + 1] << 8 | b[o + 2] << 16) + b[o + 3] * 16777216;
+var u64 = (b, o) => u32(b, o) + u32(b, o + 4) * 4294967296;
+var SIG_LOCAL = 67324752;
+var SIG_CENTRAL = 33639248;
+var SIG_END = 101010256;
+var SIG_END64 = 101075792;
+var SIG_LOCATOR64 = 117853008;
+var MAX32 = 4294967295;
+var utf8 = new TextDecoder("utf-8", { fatal: true });
+var latin1 = (b) => {
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return s;
+};
+function centralDirectory(bytes) {
+  const len = bytes.length;
+  let end = -1;
+  for (let i = len - 22; i >= Math.max(0, len - 22 - 65535); i--) {
+    if (u32(bytes, i) === SIG_END) {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) refuse("not_openable", "The file is not a zip: it has no end of central directory.");
+  const thisDisk = u16(bytes, end + 4);
+  const cdDisk = u16(bytes, end + 6);
+  if (!(thisDisk === 0 && cdDisk === 0 || thisDisk === 65535 && cdDisk === 65535)) {
+    refuse("not_openable", `The zip spans disks (its end record says disk ${thisDisk}, the directory on disk ${cdDisk}).`);
+  }
+  let cdSize = u32(bytes, end + 12);
+  let cdOffset = u32(bytes, end + 16);
+  const loc = end - 20;
+  if (loc >= 0 && u32(bytes, loc) === SIG_LOCATOR64) {
+    if (u32(bytes, loc + 4) !== 0 || u32(bytes, loc + 16) > 1) refuse("not_openable", "The zip spans disks (zip64).");
+    const rec = u64(bytes, loc + 8);
+    if (rec + 56 > len || u32(bytes, rec) !== SIG_END64) refuse("not_openable", "The zip64 end record is missing.");
+    if (u32(bytes, rec + 16) !== 0 || u32(bytes, rec + 20) !== 0) refuse("not_openable", "The zip spans disks (zip64).");
+    cdSize = u64(bytes, rec + 40);
+    cdOffset = u64(bytes, rec + 48);
+  }
+  const cdEnd = cdOffset + cdSize;
+  if (cdEnd > len) refuse("not_openable", "The central directory lies past the end of the file.");
+  const out = [];
+  let p = cdOffset;
+  while (p < cdEnd) {
+    if (p + 46 > cdEnd || u32(bytes, p) !== SIG_CENTRAL) refuse("not_openable", "The central directory is broken.");
+    const flags = u16(bytes, p + 8);
+    const nlen = u16(bytes, p + 28);
+    const elen = u16(bytes, p + 30);
+    const clen = u16(bytes, p + 32);
+    const nameBytes = bytes.subarray(p + 46, p + 46 + nlen);
+    const extra = bytes.subarray(p + 46 + nlen, p + 46 + nlen + elen);
+    let usize = u32(bytes, p + 24);
+    let csize = u32(bytes, p + 20);
+    let offset = u32(bytes, p + 42);
+    if (usize === MAX32 || csize === MAX32 || offset === MAX32) {
+      for (let q = 0; q + 4 <= extra.length; q += 4 + u16(extra, q + 2)) {
+        if (u16(extra, q) !== 1) continue;
+        let r = q + 4;
+        const stop = r + u16(extra, q + 2);
+        const next = () => {
+          if (r + 8 > stop) refuse("not_openable", "A zip64 extra field is short.");
+          const v = u64(extra, r);
+          r += 8;
+          return v;
+        };
+        if (usize === MAX32) usize = next();
+        if (csize === MAX32) csize = next();
+        if (offset === MAX32) offset = next();
+        break;
+      }
+    }
+    const nonAscii = nameBytes.some((x) => x > 127);
+    let name;
+    let badUtf8 = false;
+    if (flags & 2048) {
+      try {
+        name = utf8.decode(nameBytes);
+      } catch {
+        name = latin1(nameBytes);
+        badUtf8 = true;
+      }
+    } else {
+      name = latin1(nameBytes);
+    }
+    out.push({
+      name,
+      flags,
+      method: u16(bytes, p + 10),
+      crc: u32(bytes, p + 16),
+      csize,
+      usize,
+      offset,
+      external: u32(bytes, p + 38),
+      nonAscii,
+      badUtf8
+    });
+    p += 46 + nlen + elen + clen;
+  }
+  if (p !== cdEnd) refuse("not_openable", "The central directory is broken.");
+  return out;
+}
+var crcTable = null;
+function crc32(data) {
+  if (!crcTable) {
+    crcTable = new Int32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c2 = n;
+      for (let k = 0; k < 8; k++) c2 = c2 & 1 ? 3988292384 ^ c2 >>> 1 : c2 >>> 1;
+      crcTable[n] = c2;
+    }
+  }
+  let c = -1;
+  for (let i = 0; i < data.length; i++) c = crcTable[(c ^ data[i]) & 255] ^ c >>> 8;
+  return (c ^ -1) >>> 0;
+}
+var CHUNK = 64 * 1024;
+function inflateEntry(bytes, e) {
+  const off = e.offset;
+  if (off + 30 > bytes.length || u32(bytes, off) !== SIG_LOCAL) refuse("not_openable", `${e.name}: no local header at its offset.`);
+  const start = off + 30 + u16(bytes, off + 26) + u16(bytes, off + 28);
+  const payload = bytes.subarray(start, start + e.csize);
+  let data;
+  if (e.method === 0) {
+    data = payload;
+  } else if (payload.length <= CHUNK) {
+    try {
+      data = inflateSync(payload);
+    } catch {
+      return refuse("not_openable", `${e.name}: its deflate stream is broken.`);
+    }
+  } else {
+    const out = new Uint8Array(e.usize);
+    let n = 0;
+    let over = false;
+    const inf = new Inflate((chunk) => {
+      if (n + chunk.length > e.usize) {
+        over = true;
+        throw new Error("past its size");
+      }
+      out.set(chunk, n);
+      n += chunk.length;
+    });
+    try {
+      for (let i = 0; i < payload.length; i += CHUNK) {
+        const stop = Math.min(i + CHUNK, payload.length);
+        inf.push(payload.subarray(i, stop), stop === payload.length);
+      }
+    } catch {
+      if (!over) refuse("not_openable", `${e.name}: its deflate stream is broken.`);
+    }
+    data = over ? new Uint8Array(e.usize + 1) : out.subarray(0, n);
+  }
+  if (data.length > e.usize) refuse("too_big", `${e.name} holds more than the ${e.usize} bytes it declares.`);
+  if (data.length !== e.usize) refuse("not_openable", `${e.name} holds ${data.length} bytes and declares ${e.usize}.`);
+  if (crc32(data) !== e.crc) refuse("not_openable", `${e.name} fails its CRC.`);
+  return e.method === 0 ? data.slice() : data;
+}
 function parseWorld(data) {
   let meta;
   try {
@@ -2557,93 +2800,157 @@ function withoutLink(data, 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;
+function checkCollisions(names) {
+  const byFold = /* @__PURE__ */ new Map();
+  const segFold = /* @__PURE__ */ new Map();
+  const done = /* @__PURE__ */ new Set();
+  for (const raw of names) {
+    const segs = (raw.endsWith("/") ? raw.slice(0, -1) : raw).split("/");
+    let prefix = "";
+    let folded = "";
+    for (let i = 0; i < segs.length; i++) {
+      let f = segFold.get(segs[i]);
+      if (f === void 0) {
+        f = foldName(segs[i]);
+        segFold.set(segs[i], f);
       }
-    });
-  } catch {
-    throw new OwWorldFileError(refusal ?? "not_openable");
+      prefix = i ? `${prefix}/${segs[i]}` : segs[i];
+      folded = i ? `${folded}/${f}` : f;
+      if (done.has(prefix)) continue;
+      done.add(prefix);
+      const other = byFold.get(folded);
+      if (other !== void 0) {
+        refuse("collision", `The names ${JSON.stringify(other)} and ${JSON.stringify(prefix)} are one name after NFC and case folding.`);
+      }
+      byFold.set(folded, prefix);
+    }
   }
-  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) {
+}
+function checkFileAndFolder(files) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const n of files) {
     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 = "";
+    for (let i = 0; i < segs.length - 1; i++) {
+      prefix = i ? `${prefix}/${segs[i]}` : segs[i];
+      if (seen.has(prefix)) continue;
+      seen.add(prefix);
+      if (files.has(prefix)) refuse("unsafe_path", `${JSON.stringify(prefix)} is a file and a folder.`);
     }
   }
+}
+function readWorldFile(bytes, opts = {}) {
+  const maxBytes = opts.maxBytes ?? WORLD_FILE_MAX_BYTES;
+  const maxEntries = opts.maxEntries ?? WORLD_FILE_MAX_ENTRIES;
+  const entries = centralDirectory(bytes);
+  const seen = /* @__PURE__ */ new Set();
+  const files = [];
+  let declared = 0;
+  for (const e of entries) {
+    const name2 = e.name;
+    const isDir = name2.endsWith("/");
+    const bare = isDir ? name2.slice(0, -1) : name2;
+    const quoted = JSON.stringify(name2);
+    const fault = pathFault(bare);
+    if (fault) refuse("unsafe_path", `The entry ${quoted} ${fault}.`);
+    const kind = e.external >>> 16 & 61440;
+    if (kind !== 0 && kind !== 32768 && kind !== 16384) refuse("link", `The entry ${quoted} is a link or a special file.`);
+    if (e.flags & 65) refuse("method", `The entry ${quoted} is encrypted.`);
+    if (e.method !== 0 && e.method !== 8) refuse("method", `The entry ${quoted} uses method ${e.method} (only stored and deflate).`);
+    if (e.badUtf8) refuse("name", `The entry ${quoted} is flagged UTF-8 and is not.`);
+    if (e.nonAscii && !(e.flags & 2048)) refuse("name", `The entry ${quoted} is not ASCII and lacks the UTF-8 flag.`);
+    const bad = nameFault(bare);
+    if (bad) refuse("name", `The entry ${quoted}: ${bad}.`);
+    if (seen.has(name2)) refuse("duplicate", `The entry ${quoted} appears twice.`);
+    seen.add(name2);
+    if (isDir) continue;
+    files.push(e);
+    if (files.length > maxEntries) refuse("too_many", `The world file holds more than ${maxEntries} files.`);
+    declared += e.usize;
+    if (declared > maxBytes) refuse("too_big", `The world file declares more than ${maxBytes} bytes.`);
+  }
+  checkCollisions(seen);
+  const names = new Set(files.map((e) => e.name));
+  checkFileAndFolder(names);
+  const marker = files.find((e) => e.name === MARKER_NAME);
+  if (marker && new TextDecoder().decode(inflateEntry(bytes, marker)) !== WORLD_FILE_MEDIA_TYPE) {
+    refuse("marker", "The mimetype entry holds other bytes than the OnlyWorlds media type.");
+  }
+  const candidates = [...names].filter((n) => n !== MARKER_NAME && !isJunk(n));
   let prefix;
-  if (nameSet.has(WORLD_FILE)) {
+  if (candidates.includes(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 roots = new Set(candidates.filter((n) => n.split("/").length === 2 && n.endsWith(`/${WORLD_FILE}`) && !n.startsWith(".")).map((n) => n.slice(0, -WORLD_FILE.length)));
+    if (roots.size === 0) refuse("not_a_world", "There is no world.json at the root or in one top-level folder.");
+    if (roots.size > 1) refuse("more_than_one", `The file holds worlds in ${[...roots].join(", ")}.`);
+    prefix = [...roots][0];
+  }
+  const inside = new Set(candidates.filter((n) => n.startsWith(prefix)));
+  for (const n of inside) {
+    const rel = n.slice(prefix.length);
+    if (rel !== WORLD_FILE && rel.endsWith(`/${WORLD_FILE}`) && !rel.startsWith("records/")) {
+      refuse("more_than_one", `A second world.json sits inside the world: ${n}.`);
+    }
+  }
+  const content = /* @__PURE__ */ new Map();
+  for (const e of files) {
+    const data = inflateEntry(bytes, e);
+    if (inside.has(e.name)) content.set(e.name, data);
   }
   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 parsed = withoutLink(content.get(worldName), parseWorld(content.get(worldName)));
+  const out = [];
+  for (const [n, data] of content) {
     const path = n.slice(prefix.length);
     if (opts.skip?.(path)) continue;
-    files.push({ path, data: n === worldName ? parsed.data : raw[n] });
+    out.push({ path, data: n === worldName ? parsed.data : data });
   }
-  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  out.sort((a, b) => byCodePoint(a.path, b.path));
   const name = parsed.world.name;
   return {
     worldId: parsed.world.id,
     name: typeof name === "string" ? name : "",
     world: parsed.world,
-    files
+    files: out
   };
 }
+var PARTS = /* @__PURE__ */ new Set(["elements", "spatial", "media", "records"]);
+function carried(path) {
+  if (path === WORLD_FILE) return true;
+  const segs = path.split("/");
+  if (segs.length < 2) return false;
+  if (segs[0].startsWith(".")) return true;
+  if (!PARTS.has(segs[0])) return false;
+  if (segs[0] === "records") return true;
+  return !segs.some((s) => s.startsWith(".")) && !path.endsWith(".meta");
+}
+var STAMP = new Date(1980, 0, 1, 0, 0, 0);
 function writeWorldFile(files, topDir) {
-  if (!isSafePath(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
-  const input = {};
-  let sawWorld = false;
+  if (pathFault(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
+  const seen = /* @__PURE__ */ new Set();
   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.`);
+    if (pathFault(f.path)) throw new OwWorldFileError("unsafe_path");
+    if (seen.has(f.path)) throw new OwWorldFileError("unsafe_path", `The path ${f.path} is listed twice.`);
+    seen.add(f.path);
+  }
+  const kept = files.filter((f) => carried(f.path));
+  if (!kept.some((f) => f.path === WORLD_FILE)) throw new OwWorldFileError("not_a_world");
+  const keys = kept.map((f) => `${topDir}/${f.path}`);
+  for (const key of keys) {
+    const bad = nameFault(key);
+    if (bad) throw new OwWorldFileError("name", `The path ${key}: ${bad}.`);
+  }
+  checkCollisions([MARKER_NAME, ...keys]);
+  checkFileAndFolder(/* @__PURE__ */ new Set([MARKER_NAME, ...keys]));
+  const input = {
+    [MARKER_NAME]: [new TextEncoder().encode(WORLD_FILE_MEDIA_TYPE), { level: 0, mtime: STAMP }]
+  };
+  for (const f of [...kept].sort((a, b) => byCodePoint(a.path, b.path))) {
     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 (f.path === WORLD_FILE) data = withoutLink(data, parseWorld(data)).data;
+    input[`${topDir}/${f.path}`] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0, mtime: STAMP }];
   }
-  if (!sawWorld) throw new OwWorldFileError("not_a_world");
   return zipSync(input);
 }
 
@@ -3885,6 +4192,7 @@ export {
   TokenResource,
   WORLD_FILE_MAX_BYTES,
   WORLD_FILE_MAX_ENTRIES,
+  WORLD_FILE_MEDIA_TYPE,
   absYearForEraYear,
   absoluteYear,
   approxYearLength,
@@ -3928,6 +4236,7 @@ export {
   renderElement,
   resolveCalendarLens,
   resolveEraDomains,
+  simpleCaseFold,
   validateCalendarConfig,
   weekdayForStep,
   worldCalendars,

package/package.json

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