@onlyworlds/sdk 4.134.1 → 4.135.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,18 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.135.1] - 2026-11-09
9
+
10
+ ### Fixed
11
+
12
+ - `trailByPlace` no longer runs forever when a row of the frame has no free point left: more Pins on one row (one y and z) than the frame is wide plus one. It is refused with a TypeError naming the element, its row and the frame's width. A taken point tries every x on its row first, as before. The shared fixture gains the boundary pair (two on one point in a frame 1 wide fit; a third is refused) and a pin given as whole floats, whose words read as whole numbers.
13
+
14
+ ## [4.135.0] - 2026-11-09
15
+
16
+ ### Added
17
+
18
+ - `trailByPlace(input)`: the first layout method, a world laid out along a route on a ground map, answered as a layout in the standard's own fields: a Map frame (`width`, `height`, `depth`), one Pin per element (whole numbers in the Map's pixels, which `mapSpace` reads back), the route, and the recipe (`method: 'trail-by-place'` and the settings it ran with, so the same layout runs again from the Map alone). The places come in travel order, each at its own pin on the ground map plus a margin, evenly between two pinned places, or on a ring inside a parent place. Every other element hangs on one spiral round the place it belongs to (the mean of its places' points), the hero first, then by floor and id, at its floor's height. Nothing shares a place's own point, and no two Pins share a point: a taken point moves along x from its own point, one pixel right, one left, two right, and on, by element id order. Each Pin carries `by`, the caller's words followed by the method's own. The method places and does not read: which elements are in, the travel order and what hangs where are the caller's. Points round half to even. An input it cannot place is a TypeError naming what, an unknown key at any level included. `TRAIL_TIERS` is the default floors; `roundHalfEven` the rounding.
19
+
8
20
  ## [4.134.1] - 2026-11-08
9
21
 
10
22
  ### Fixed
package/README.md CHANGED
@@ -31,7 +31,7 @@ Moppetopia
31
31
 
32
32
  ## Your own world
33
33
 
34
- Create a world at [onlyworlds.com](https://www.onlyworlds.com); its keys are on the world's page. A new key is shown once, so copy it then.
34
+ Create a world at [onlyworlds.com](https://www.onlyworlds.com); its keys are on its world page. A new key is shown once, so copy it then.
35
35
 
36
36
  - An `ow_r_` key reads, with no PIN. It is the key to give to players or a public site.
37
37
  - An `ow_w_` key reads and writes. Writes also send a PIN as `apiPin`.
package/dist/index.d.ts CHANGED
@@ -5869,6 +5869,115 @@ interface OwMapSpace {
5869
5869
  */
5870
5870
  declare function mapSpace(elements: readonly unknown[]): OwMapSpace;
5871
5871
 
5872
+ /** A place on the route, in travel order. Exactly one of `pin`, `between` or `parent` says where it sits. */
5873
+ interface OwTrailPlace {
5874
+ id: string;
5875
+ type: string;
5876
+ name: string;
5877
+ /** Its point on the ground map, `[x, y]` in the ground map's pixels (the margin is added). */
5878
+ pin?: [number, number];
5879
+ /** Two pinned places it sits between, evenly, with any others between the same two, in travel order. */
5880
+ between?: [string, string];
5881
+ /** A place it sits inside: on a ring round that place, siblings by id. */
5882
+ parent?: string;
5883
+ /** The caller's words for why it sits there: a pinned place's whole `by` line; a `between` or `parent` place's reason. */
5884
+ by?: string;
5885
+ }
5886
+ /** An element that hangs from one or more places: on the spiral round their point (the mean of their points). */
5887
+ interface OwTrailHanger {
5888
+ id: string;
5889
+ type: string;
5890
+ name: string;
5891
+ /** The places it hangs from, by id; each must be one of `places`. */
5892
+ at: string[];
5893
+ /** The caller's words for why it hangs there; the method adds its tier and its place on the spiral. */
5894
+ by?: string;
5895
+ }
5896
+ /** One floor of the layout: the kinds (element type words) that stand at this height. */
5897
+ interface OwTrailTier {
5898
+ name: string;
5899
+ z: number;
5900
+ kinds: string[];
5901
+ }
5902
+ interface OwTrailSpiral {
5903
+ /** The first member's distance from the place's point, in pixels; above 0, so nothing shares a place's own point. */
5904
+ r0: number;
5905
+ /** The n-th member stands at `r0 + c * sqrt(n)`. */
5906
+ c: number;
5907
+ /** The turn between members, in radians, `n * angle`. */
5908
+ angle: number;
5909
+ }
5910
+ /** The method's settings: what a Map's recipe carries, so the layout can be run again from the Map alone. */
5911
+ interface OwTrailSettings {
5912
+ /** The ground map's own frame; the layout's frame is it plus `margin` on every side. */
5913
+ ground: {
5914
+ width: number;
5915
+ height: number;
5916
+ };
5917
+ margin: number;
5918
+ depth: number;
5919
+ tiers: OwTrailTier[];
5920
+ spiral: OwTrailSpiral;
5921
+ /** How far a place sits from the place it is inside. */
5922
+ parentRing: number;
5923
+ }
5924
+ interface OwTrailInput extends Partial<Omit<OwTrailSettings, 'ground' | 'depth'>> {
5925
+ ground: {
5926
+ width: number;
5927
+ height: number;
5928
+ };
5929
+ depth: number;
5930
+ places: OwTrailPlace[];
5931
+ hangers: OwTrailHanger[];
5932
+ /** Stands first on its place's spiral. */
5933
+ hero?: OwTrailHanger;
5934
+ }
5935
+ interface OwTrailPin {
5936
+ element_type: string;
5937
+ element_id: string;
5938
+ name: string;
5939
+ x: number;
5940
+ y: number;
5941
+ z: number;
5942
+ /** Why it stands there, in plain words. */
5943
+ by: string;
5944
+ }
5945
+ interface OwTrailLayout {
5946
+ /** The layout Map's frame. */
5947
+ map: {
5948
+ width: number;
5949
+ height: number;
5950
+ depth: number;
5951
+ };
5952
+ /** One per place, hanger and hero, sorted by element id (code point order). */
5953
+ pins: OwTrailPin[];
5954
+ /** The places' points in travel order, `[x, y, 0]`, rounded and not moved. */
5955
+ route: [number, number, number][];
5956
+ /** The method and the settings it ran with, for the Map's recipe. */
5957
+ recipe: {
5958
+ method: 'trail-by-place';
5959
+ settings: OwTrailSettings;
5960
+ };
5961
+ /** Points moved one pixel at a time off a point already taken, and points pulled back inside the frame. */
5962
+ nudged: number;
5963
+ clamped: number;
5964
+ }
5965
+ /** The default floors: places and things on the ground, the living above, what happened higher, what is told highest. */
5966
+ declare const TRAIL_TIERS: readonly OwTrailTier[];
5967
+ /** Round half to even on the number's exact value (the rounding both packages use, so they agree to the pixel). */
5968
+ declare function roundHalfEven(v: number): number;
5969
+ /**
5970
+ * Lay out a trail. Places first: a pinned place at its pin plus the margin; a place `between` two pinned places
5971
+ * evenly along the line between them, with the others between the same two, in travel order; a place inside a
5972
+ * `parent` on a ring round it. Then every hanger and the hero: grouped by the rounded mean of their places' points,
5973
+ * each group on one sunflower spiral round that point (the hero first, then by tier, then by id; the n-th member at
5974
+ * `r0 + c * sqrt(n)` and `n * angle`), at its tier's height. Last, every point is rounded half to even, kept inside
5975
+ * the frame, and, by element id order, a point already taken moves along x from its own point (one pixel right, one
5976
+ * left, two right, two left, and on), so no two Pins share a point. Throws a TypeError, naming what, on an input it cannot place: an unknown key, a place with no one rule, a
5977
+ * reference to a place it does not hold, a kind with no tier, an id twice, a row of the frame with no free point left.
5978
+ */
5979
+ declare function trailByPlace(input: OwTrailInput): OwTrailLayout;
5980
+
5872
5981
  /** One word pair of a names map: `one` for a single thing, `many` for a plural (absent: `one`). */
5873
5982
  interface OwWordPair {
5874
5983
  one: string;
@@ -7232,4 +7341,4 @@ declare class TokenResource {
7232
7341
  getEncryptionInfo(): Promise<EncryptionInfo>;
7233
7342
  }
7234
7343
 
7235
- export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, CHARTER_PAIRS, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, DATE_FIELD, ELEMENT_FAMILIES, ELEMENT_GROUPS, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementGroup, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GROUP_COLORS, GROUP_ORDER, GameTier, type ListParams, MESSAGE_PAIR, NOTE_PAIR, ONLYWORLDS_VERSION, type OwAccountToken, type OwAccountWorld, type OwAddress, OwAddressError, type OwAddressForm, type OwAddressReading, type OwAddressReason, type OwAddressingOptions, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwCharterWorld, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDoor, type OwDragField, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtLens, type OwDraughtPolicy, type OwEdited, type OwElement, type OwElementBase, type OwElementMark, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwGraphCutReason, type OwGraphEdge, type OwGraphMark, type OwGraphNode, type OwGraphOptions, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLanding, type OwLandingCluster, type OwLandingGap, type OwLandingGapKind, type OwLandingMember, type OwLandingMode, type OwLandingOptions, type OwLensCutReason, type OwLensMail, type OwLensOptions, type OwLensReader, type OwLensReading, type OwLensWorld, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMapSpace, type OwMapSpaceMap, type OwMapSpaceOutReason, type OwMapSpaceOutline, type OwMapSpacePin, type OwMapSpacePoint, type OwMe, type OwMediaTicket, type OwMember, type OwMemberLenses, type OwMemberRole, type OwMessageMember, type OwMintedKey, type OwMySeat, type OwNamesMap, OwNetworkError, type OwOpener, type OwOpenerKind, type OwOpenerState, type OwOpenerSurface, type OwOpenersOptions, type OwPage, type OwPaidBy, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedMark, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwReadingAids, type OwReadingAidsCharter, type OwReadingAidsDomain, type OwReadingAidsGuide, type OwReadingAidsHub, type OwRecord, type OwRecordMark, type OwRecordStory, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSender, type OwSenderStatus, type OwServedReadingAids, 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, OwStaleProposalError, type OwStrand, type OwStrandSlot, type OwStrandWorld, type OwTool, type OwToolNeeds, type OwToolOpen, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, type OwWorldKeyMember, type OwWorldKeyRow, type OwWorldLens, type OwWorldLensReading, type OwWorldLenses, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PROPOSED_MARK, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, RECORD_FIELD, REVIEW_PROPOSED_LABEL, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, STRAND_FIELD, type SectionInfo, type StepBreakdown, TOOLS, 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, charterOf, dateOf, degreeOf, detectKeyKind, displayYear, domainsOf, doorWhere, doorsOf, dragField, draughtText, editedBy, elementAddress, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, groupOf, handsOnAsProposed, hasUnseenRecipients, intercalaryInYear, isAddressedTo, isAgentDoor, isCharterElement, isDemoKey, isKnownOf, isLeapYear, isLens, isMessage, isNote, isParseError, isRoomElement, isSentBy, isTemplate, isToEveryone, kindCanWrite, landingOf, lensesInUse, lookupWorld, mapSpace, monthStartSteps, nfc, noteOf, openersFor, outDegreeOf, parseDate, parseErrorEnvelope, parseOwLink, pinExpectation, pkceChallenge, planPhoto, preparePhoto, proposedMarkOf, readCalendarConfig, readCalendarValue, readMarkOf, readWorldFile, readingAidOf, recipientsOf, recordMarkOf, recordsOf, renderElement, resolveCalendar, resolveCalendarLens, resolveEraDomains, resolveLens, senderStatus, simpleCaseFold, strandOf, threadOf, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
7344
+ export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, CHARTER_PAIRS, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, DATE_FIELD, ELEMENT_FAMILIES, ELEMENT_GROUPS, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementGroup, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GROUP_COLORS, GROUP_ORDER, GameTier, type ListParams, MESSAGE_PAIR, NOTE_PAIR, ONLYWORLDS_VERSION, type OwAccountToken, type OwAccountWorld, type OwAddress, OwAddressError, type OwAddressForm, type OwAddressReading, type OwAddressReason, type OwAddressingOptions, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwCharterWorld, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDoor, type OwDragField, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtLens, type OwDraughtPolicy, type OwEdited, type OwElement, type OwElementBase, type OwElementMark, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwGraphCutReason, type OwGraphEdge, type OwGraphMark, type OwGraphNode, type OwGraphOptions, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLanding, type OwLandingCluster, type OwLandingGap, type OwLandingGapKind, type OwLandingMember, type OwLandingMode, type OwLandingOptions, type OwLensCutReason, type OwLensMail, type OwLensOptions, type OwLensReader, type OwLensReading, type OwLensWorld, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMapSpace, type OwMapSpaceMap, type OwMapSpaceOutReason, type OwMapSpaceOutline, type OwMapSpacePin, type OwMapSpacePoint, type OwMe, type OwMediaTicket, type OwMember, type OwMemberLenses, type OwMemberRole, type OwMessageMember, type OwMintedKey, type OwMySeat, type OwNamesMap, OwNetworkError, type OwOpener, type OwOpenerKind, type OwOpenerState, type OwOpenerSurface, type OwOpenersOptions, type OwPage, type OwPaidBy, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedMark, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwReadingAids, type OwReadingAidsCharter, type OwReadingAidsDomain, type OwReadingAidsGuide, type OwReadingAidsHub, type OwRecord, type OwRecordMark, type OwRecordStory, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSender, type OwSenderStatus, type OwServedReadingAids, 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, OwStaleProposalError, type OwStrand, type OwStrandSlot, type OwStrandWorld, type OwTool, type OwToolNeeds, type OwToolOpen, type OwTrailHanger, type OwTrailInput, type OwTrailLayout, type OwTrailPin, type OwTrailPlace, type OwTrailSettings, type OwTrailSpiral, type OwTrailTier, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, type OwWorldKeyMember, type OwWorldKeyRow, type OwWorldLens, type OwWorldLensReading, type OwWorldLenses, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PROPOSED_MARK, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, RECORD_FIELD, REVIEW_PROPOSED_LABEL, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, STRAND_FIELD, type SectionInfo, type StepBreakdown, TOOLS, TRAIL_TIERS, 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, charterOf, dateOf, degreeOf, detectKeyKind, displayYear, domainsOf, doorWhere, doorsOf, dragField, draughtText, editedBy, elementAddress, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, groupOf, handsOnAsProposed, hasUnseenRecipients, intercalaryInYear, isAddressedTo, isAgentDoor, isCharterElement, isDemoKey, isKnownOf, isLeapYear, isLens, isMessage, isNote, isParseError, isRoomElement, isSentBy, isTemplate, isToEveryone, kindCanWrite, landingOf, lensesInUse, lookupWorld, mapSpace, monthStartSteps, nfc, noteOf, openersFor, outDegreeOf, parseDate, parseErrorEnvelope, parseOwLink, pinExpectation, pkceChallenge, planPhoto, preparePhoto, proposedMarkOf, readCalendarConfig, readCalendarValue, readMarkOf, readWorldFile, readingAidOf, recipientsOf, recordMarkOf, recordsOf, renderElement, resolveCalendar, resolveCalendarLens, resolveEraDomains, resolveLens, roundHalfEven, senderStatus, simpleCaseFold, strandOf, threadOf, trailByPlace, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
package/dist/index.js CHANGED
@@ -2373,17 +2373,17 @@ function xhrUpload(XHR, url, headers, body, total, onProgress) {
2373
2373
  last = loaded;
2374
2374
  onProgress(loaded, total);
2375
2375
  };
2376
- const fail = (why) => () => reject(new OwNetworkError(`OnlyWorlds file upload failed: POST ${url}`, new Error(why)));
2376
+ const fail2 = (why) => () => reject(new OwNetworkError(`OnlyWorlds file upload failed: POST ${url}`, new Error(why)));
2377
2377
  xhr.open("POST", url);
2378
2378
  for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
2379
2379
  if (xhr.upload) xhr.upload.onprogress = (e) => report(Math.min(e.loaded, total));
2380
- xhr.onerror = fail("network error");
2381
- xhr.onabort = fail("aborted");
2382
- xhr.ontimeout = fail("timed out");
2380
+ xhr.onerror = fail2("network error");
2381
+ xhr.onabort = fail2("aborted");
2382
+ xhr.ontimeout = fail2("timed out");
2383
2383
  xhr.onload = () => {
2384
2384
  const status = xhr.status;
2385
2385
  if (!status) {
2386
- fail("no answer")();
2386
+ fail2("no answer")();
2387
2387
  return;
2388
2388
  }
2389
2389
  const ok = status >= 200 && status < 300;
@@ -4035,6 +4035,206 @@ function mapSpace(elements) {
4035
4035
  return { maps: mapRows, zones: outlines, pins, out: counted };
4036
4036
  }
4037
4037
 
4038
+ // src/layout-trail.ts
4039
+ var TRAIL_TIERS = Object.freeze([
4040
+ { name: "ground: places and things", z: 0, kinds: ["location", "object", "zone"] },
4041
+ { name: "people and the living", z: 240, kinds: ["character", "collective", "creature", "species"] },
4042
+ { name: "what happened", z: 480, kinds: ["event"] },
4043
+ { name: "told or abstract", z: 720, kinds: ["ability", "construct", "family", "institution", "language", "law", "narrative", "phenomenon", "relation", "title", "trait"] }
4044
+ ].map((t) => Object.freeze({ ...t, kinds: Object.freeze([...t.kinds]) })));
4045
+ var DEFAULT_SPIRAL = { r0: 140, c: 20, angle: 2.399963 };
4046
+ var DEFAULT_PARENT_RING = 140;
4047
+ function roundHalfEven(v) {
4048
+ const f = Math.floor(v);
4049
+ const d = v - f;
4050
+ if (d > 0.5) return f + 1;
4051
+ if (d < 0.5) return f;
4052
+ return f % 2 === 0 ? f : f + 1;
4053
+ }
4054
+ var INPUT_KEYS = ["ground", "margin", "depth", "tiers", "spiral", "parentRing", "places", "hangers", "hero"];
4055
+ var PLACE_KEYS = ["id", "type", "name", "pin", "between", "parent", "by"];
4056
+ var HANGER_KEYS = ["id", "type", "name", "at", "by"];
4057
+ function fail(msg) {
4058
+ throw new TypeError(`trailByPlace: ${msg}`);
4059
+ }
4060
+ var finite = (v) => typeof v === "number" && Number.isFinite(v);
4061
+ var wholeAbove = (v, min) => typeof v === "number" && Number.isSafeInteger(v) && v > min;
4062
+ function checkElement(e, what, keys) {
4063
+ if (!e || typeof e !== "object" || Array.isArray(e)) fail(`${what} is not an object`);
4064
+ refuseUnknownOptions(`trailByPlace: ${what}`, e, keys);
4065
+ const o = e;
4066
+ if (typeof o.id !== "string" || !o.id) fail(`${what} has no id`);
4067
+ if (typeof o.type !== "string" || !o.type) fail(`${what} (${o.id}) has no type`);
4068
+ if (typeof o.name !== "string") fail(`${what} (${o.id}) has no name`);
4069
+ if (o.by !== void 0 && typeof o.by !== "string") fail(`${what} (${o.id}): by is not a string`);
4070
+ }
4071
+ function trailByPlace(input) {
4072
+ if (!input || typeof input !== "object") fail("the input is not an object");
4073
+ refuseUnknownOptions("trailByPlace", input, INPUT_KEYS);
4074
+ const { places, hangers, hero } = input;
4075
+ const g = input.ground;
4076
+ if (!g || typeof g !== "object") fail("no ground");
4077
+ refuseUnknownOptions("trailByPlace: ground", g, ["width", "height"]);
4078
+ if (!wholeAbove(g.width, 0) || !wholeAbove(g.height, 0)) fail("the ground's width and height are whole numbers above 0");
4079
+ const margin = input.margin ?? 0;
4080
+ if (!Number.isSafeInteger(margin) || margin < 0) fail("margin is a whole number, 0 or more");
4081
+ if (!wholeAbove(input.depth, 0)) fail("depth is a whole number above 0");
4082
+ const spiral = input.spiral ?? DEFAULT_SPIRAL;
4083
+ refuseUnknownOptions("trailByPlace: spiral", spiral, ["r0", "c", "angle"]);
4084
+ if (!finite(spiral.r0) || spiral.r0 <= 0 || !finite(spiral.c) || spiral.c < 0 || !finite(spiral.angle)) {
4085
+ fail("spiral is {r0 above 0, c 0 or more, angle}");
4086
+ }
4087
+ const parentRing = input.parentRing ?? DEFAULT_PARENT_RING;
4088
+ if (!finite(parentRing) || parentRing <= 0) fail("parentRing is a number above 0");
4089
+ const tiers = input.tiers ?? TRAIL_TIERS;
4090
+ if (!Array.isArray(tiers) || tiers.length === 0) fail("tiers is a list of at least one tier");
4091
+ for (const t of tiers) {
4092
+ refuseUnknownOptions("trailByPlace: tier", t, ["name", "z", "kinds"]);
4093
+ if (typeof t.name !== "string" || !Number.isSafeInteger(t.z) || t.z < 0 || !Array.isArray(t.kinds)) fail("a tier is {name, z (a whole number, 0 or more), kinds}");
4094
+ }
4095
+ const tierOf = (type, id) => {
4096
+ const k = tiers.findIndex((t) => t.kinds.includes(type));
4097
+ if (k < 0) fail(`no tier holds the kind '${type}' (${id})`);
4098
+ return k;
4099
+ };
4100
+ if (!Array.isArray(places) || places.length === 0) fail("places is a list of at least one place");
4101
+ if (!Array.isArray(hangers)) fail("hangers is a list");
4102
+ const M = margin;
4103
+ const W = g.width + 2 * M;
4104
+ const H = g.height + 2 * M;
4105
+ const D = input.depth;
4106
+ const seenIds = /* @__PURE__ */ new Set();
4107
+ const once = (id) => {
4108
+ if (seenIds.has(id)) fail(`the id ${id} is given twice`);
4109
+ seenIds.add(id);
4110
+ };
4111
+ const placeById = /* @__PURE__ */ new Map();
4112
+ for (const [i, p] of places.entries()) {
4113
+ checkElement(p, `place ${i}`, PLACE_KEYS);
4114
+ once(p.id);
4115
+ const rules = ["pin", "between", "parent"].filter((k) => p[k] !== void 0);
4116
+ if (rules.length !== 1) fail(`place ${p.name} (${p.id}) needs exactly one of pin, between, parent; it has ${rules.length ? rules.join(", ") : "none"}`);
4117
+ if (p.pin !== void 0 && !(Array.isArray(p.pin) && p.pin.length === 2 && p.pin.every(finite))) fail(`place ${p.name}: pin is [x, y]`);
4118
+ if (p.between !== void 0 && !(Array.isArray(p.between) && p.between.length === 2 && p.between.every((v) => typeof v === "string"))) fail(`place ${p.name}: between is [place id, place id]`);
4119
+ if (p.parent !== void 0 && typeof p.parent !== "string") fail(`place ${p.name}: parent is a place id`);
4120
+ placeById.set(p.id, p);
4121
+ }
4122
+ const pt = /* @__PURE__ */ new Map();
4123
+ const by = /* @__PURE__ */ new Map();
4124
+ for (const p of places) {
4125
+ if (!p.pin) continue;
4126
+ pt.set(p.id, [p.pin[0] + M, p.pin[1] + M]);
4127
+ by.set(p.id, p.by ?? `its pin on the ground (${p.pin[0]}, ${p.pin[1]}), plus the ${M} px margin`);
4128
+ }
4129
+ const groups = /* @__PURE__ */ new Map();
4130
+ for (const p of places) {
4131
+ if (!p.between) continue;
4132
+ for (const end of p.between) {
4133
+ if (!placeById.has(end)) fail(`place ${p.name}: between names ${end}, which is not one of the places`);
4134
+ if (!pt.has(end)) fail(`place ${p.name}: between names ${placeById.get(end).name}, which has no pin`);
4135
+ }
4136
+ const k = `${p.between[0]}\0${p.between[1]}`;
4137
+ if (!groups.has(k)) groups.set(k, []);
4138
+ groups.get(k).push(p);
4139
+ }
4140
+ for (const ids of groups.values()) {
4141
+ ids.forEach((p, n) => {
4142
+ const [a, b] = p.between;
4143
+ const f = (n + 1) / (ids.length + 1);
4144
+ const pa = pt.get(a);
4145
+ const pb = pt.get(b);
4146
+ pt.set(p.id, [pa[0] + (pb[0] - pa[0]) * f, pa[1] + (pb[1] - pa[1]) * f]);
4147
+ const base = `no pin: between ${placeById.get(a).name} and ${placeById.get(b).name}`;
4148
+ by.set(p.id, p.by ? `${base} (${p.by})` : base);
4149
+ });
4150
+ }
4151
+ const sibs = /* @__PURE__ */ new Map();
4152
+ for (const p of places) {
4153
+ if (!p.parent) continue;
4154
+ if (!placeById.has(p.parent)) fail(`place ${p.name}: parent ${p.parent} is not one of the places`);
4155
+ if (!sibs.has(p.parent)) sibs.set(p.parent, []);
4156
+ sibs.get(p.parent).push(p.id);
4157
+ }
4158
+ for (const s of sibs.values()) s.sort(byCodePoint);
4159
+ for (let pass = 0, left = true; left && pass <= places.length; pass++) {
4160
+ left = false;
4161
+ for (const p of places) {
4162
+ if (!p.parent || pt.has(p.id)) continue;
4163
+ const c = pt.get(p.parent);
4164
+ if (!c) {
4165
+ left = true;
4166
+ continue;
4167
+ }
4168
+ const s = sibs.get(p.parent);
4169
+ const a = Math.PI / 4 + 2 * Math.PI * s.indexOf(p.id) / s.length;
4170
+ pt.set(p.id, [c[0] + parentRing * Math.cos(a), c[1] + parentRing * Math.sin(a)]);
4171
+ by.set(p.id, `no pin: inside ${placeById.get(p.parent).name} (${p.by ?? "its parent_location"}), beside it`);
4172
+ }
4173
+ }
4174
+ for (const p of places) if (!pt.has(p.id)) fail(`place ${p.name} (${p.id}) sits inside a ring of parents that never reaches a placed place`);
4175
+ const raw = places.map((p) => ({ element_type: p.type, element_id: p.id, name: p.name, x: pt.get(p.id)[0], y: pt.get(p.id)[1], z: 0, by: by.get(p.id) }));
4176
+ const members = [...hangers.map((h, i) => ({ h, what: `hanger ${i}` })), ...hero ? [{ h: hero, what: "the hero" }] : []];
4177
+ const clusters = /* @__PURE__ */ new Map();
4178
+ for (const { h, what } of members) {
4179
+ checkElement(h, what, HANGER_KEYS);
4180
+ once(h.id);
4181
+ if (!Array.isArray(h.at) || h.at.length === 0) fail(`${what} ${h.name}: at is a list of at least one place id`);
4182
+ for (const q of h.at) if (!pt.has(q)) fail(`${what} ${h.name}: at names ${q}, which is not one of the places`);
4183
+ const cx = roundHalfEven(h.at.reduce((s, q) => s + pt.get(q)[0], 0) / h.at.length);
4184
+ const cy = roundHalfEven(h.at.reduce((s, q) => s + pt.get(q)[1], 0) / h.at.length);
4185
+ const k = `${cx},${cy}`;
4186
+ if (!clusters.has(k)) clusters.set(k, { cx, cy, hs: [] });
4187
+ clusters.get(k).hs.push({ h, tier: tierOf(h.type, h.id) });
4188
+ }
4189
+ const heroId = hero?.id;
4190
+ for (const { cx, cy, hs } of clusters.values()) {
4191
+ hs.sort((p, q) => Number(p.h.id !== heroId) - Number(q.h.id !== heroId) || p.tier - q.tier || byCodePoint(p.h.id, q.h.id));
4192
+ hs.forEach(({ h, tier }, n) => {
4193
+ const r = spiral.r0 + spiral.c * Math.sqrt(n);
4194
+ const a = n * spiral.angle;
4195
+ const where = `tier ${tiers[tier].name}; ${n + 1} of ${hs.length} on the spiral round it`;
4196
+ raw.push({ element_type: h.type, element_id: h.id, name: h.name, x: cx + r * Math.cos(a), y: cy + r * Math.sin(a), z: tiers[tier].z, by: h.by ? `${h.by}; ${where}` : where });
4197
+ });
4198
+ }
4199
+ raw.sort((p, q) => byCodePoint(p.element_id, q.element_id));
4200
+ const taken = /* @__PURE__ */ new Set();
4201
+ let nudged = 0;
4202
+ let clamped = 0;
4203
+ for (const p of raw) {
4204
+ for (const [k, hi] of [["x", W], ["y", H], ["z", D]]) {
4205
+ const v = roundHalfEven(p[k]);
4206
+ const c = Math.min(Math.max(v, 0), hi);
4207
+ if (c !== v) clamped++;
4208
+ p[k] = c;
4209
+ }
4210
+ const x0 = p.x;
4211
+ for (let step = 1; taken.has(`${p.x},${p.y},${p.z}`); step++) {
4212
+ if (step > 2 * W + 2) fail(`no free point left for ${p.name} (${p.element_id}) on its row (y ${p.y}, z ${p.z}): the frame is ${W} wide`);
4213
+ p.x = Math.min(Math.max(x0 + (step % 2 ? 1 : -1) * Math.floor((step + 1) / 2), 0), W);
4214
+ nudged++;
4215
+ }
4216
+ taken.add(`${p.x},${p.y},${p.z}`);
4217
+ }
4218
+ return {
4219
+ map: { width: W, height: H, depth: D },
4220
+ pins: raw,
4221
+ route: places.map((p) => [roundHalfEven(pt.get(p.id)[0]), roundHalfEven(pt.get(p.id)[1]), 0]),
4222
+ recipe: {
4223
+ method: "trail-by-place",
4224
+ settings: {
4225
+ ground: { width: g.width, height: g.height },
4226
+ margin: M,
4227
+ depth: D,
4228
+ tiers: tiers.map((t) => ({ name: t.name, z: t.z, kinds: [...t.kinds] })),
4229
+ spiral: { r0: spiral.r0, c: spiral.c, angle: spiral.angle },
4230
+ parentRing
4231
+ }
4232
+ },
4233
+ nudged,
4234
+ clamped
4235
+ };
4236
+ }
4237
+
4038
4238
  // src/drag.ts
4039
4239
  var TYPES = new Set(ELEMENT_TYPES);
4040
4240
  function dragField(a, b) {
@@ -6281,6 +6481,7 @@ export {
6281
6481
  SPATIAL_TYPES,
6282
6482
  STRAND_FIELD,
6283
6483
  TOOLS,
6484
+ TRAIL_TIERS,
6284
6485
  TokenResource,
6285
6486
  WORLD_FILE_MAX_BYTES,
6286
6487
  WORLD_FILE_MAX_ENTRIES,
@@ -6367,10 +6568,12 @@ export {
6367
6568
  resolveCalendarLens,
6368
6569
  resolveEraDomains,
6369
6570
  resolveLens,
6571
+ roundHalfEven,
6370
6572
  senderStatus,
6371
6573
  simpleCaseFold,
6372
6574
  strandOf,
6373
6575
  threadOf,
6576
+ trailByPlace,
6374
6577
  typeWord,
6375
6578
  unreadFor,
6376
6579
  validateCalendarConfig,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.134.1",
3
+ "version": "4.135.1",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {