@onlyworlds/sdk 4.125.0 → 4.127.0

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/AGENTS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # For AI agents using @onlyworlds/sdk
2
2
 
3
- **Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.102** (canonical 00.33.00).
3
+ **Current as of**: SDK **4.x** · schema-dist **v0.34.0-dist.103** (canonical 00.34.00).
4
4
  This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
5
5
  re-read against it, the check fails rather than letting this document rot quietly.
6
6
 
@@ -223,7 +223,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
223
223
  address in a field is text: never fetch it to show what it names.
224
224
  - To offer a world or an element in other tools, `openersFor(TOOLS, kind, address, surface)` gives
225
225
  the "Open with" rows in order, each `{ id, name, href, state }` with its word ("Sign in to Atlas
226
- first") or null. Draw them as given; never word a row yourself.
226
+ first") or null. Draw them as given; never word a row yourself. For an element, pass it as served
227
+ (`openersFor(TOOLS, 'element', address, surface, { element })`): a tool that cannot open it (a
228
+ room, hidden or proposed element, map space, a reading aid) then has no row.
227
229
  - A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
228
230
  Slice strings by code point, not by UTF-16 unit.
229
231
  - Colour carries the element's colour group (`elementColor(type, mode)`, `groupOf(type)`: `blue`,
package/CHANGELOG.md CHANGED
@@ -5,6 +5,33 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.127.0] - 2026-11-02
9
+
10
+ ### Added
11
+
12
+ - **`landingOf(graph, options)`: the landing profile** (schema-dist `profiles/landing.md`, serial 103). A world's first picture at a door, read from the graph `worldGraph` answers for the visitor, so it holds only what that reader may see. The answer is `{ mode, size, clusters, unclustered, gaps }`, all five keys always present: `mode` is `gaps` when the graph has fewer nodes than `size` (default 24), else `graph`; `clusters` are the most-linked Characters (at most `heads`, default 5), each with the nodes within `hops` steps of it (default 1), a node joining its nearest head; `unclustered` is every node no head reaches; `gaps` are the orphans, the near-orphans, a Character whose `location` names no Location in the graph (`no_place`) and a Location no Character's `location` names (`nobody_here`). Counted in integers, ids in code point order, so the same graph and options give the same bytes. An unknown option, or one that is not a whole number of 1 or more, is refused by name. The fixture `profiles/landing.fixture.json` (30 cases) is the test. Types: `OwLanding`, `OwLandingCluster`, `OwLandingMember`, `OwLandingGap`, `OwLandingGapKind`, `OwLandingMode`, `OwLandingOptions`.
13
+ - **`LocationV2.vehicle`**, from canonical 00.34.00: a single link to the Object a place is the inside of (a ship, a train, a walking city), for a place that moves with the thing; a place inside another place still uses `parent_location`. It is in `FIELD_SCHEMA`, `SINGLE_LINK_FIELDS`, the Location's Setting section (after `parent_location`) and `SCHEMA.md`.
14
+
15
+ ### Changed
16
+
17
+ - **Schema repinned to schema-dist `v0.34.0-dist.103`** (from dist.102), canonical **00.34.00**, so `ONLYWORLDS_VERSION` is now `'00.34.00'`. Serial 103 adds `vehicle` to Location, the landing profile, the lens profile graph section's degree and out-degree with the lens fixture's `degree` cases (196 cases in all; `degreeOf` and `outDegreeOf` answer the five new ones as they stood), and seven readings in the record profile (its fixture from 32 cases to 40).
18
+ - **`recordsOf` reads a run or a story as proposed exactly when `proposedMarkOf` does.** An empty mark (`{}`, `""` or `[]`) is settled, so a run or story carrying one is now read; before, any value but null left it out.
19
+ - **`recordsOf` never reads an Event or a Narrative whose `id` is not a string**: no entry without an id, and no error. Before, a run with a numeric id was returned with that number as its id. The record profile's other new cases (`played_at`'s upper-case `T` and `Z` and ASCII digits, a name that is not a string, ties by code point) pass as the reader stood.
20
+ - **`TOOLS` repinned at the tools list's `f10afdc`**: Tactical Tangle is a listed row (`tangle`). It has no open door, so `openersFor` offers it nowhere, and a record whose `tool` is `tangle` finds its row by id.
21
+ - **A reading builds its reverse link index only when a lens hop asks for it.** `worldGraph` without a lens, and every other reading that walks no hop, no longer pays for it; no answer changes. On a 20,573-element world, `worldGraph` for the owner went from a median 434 ms to 324 ms, both builds interleaved in one process.
22
+
23
+ ## [4.126.0] - 2026-11-01
24
+
25
+ ### Added
26
+
27
+ - **`openersFor(tools, kind, address, surface, { element })`: no row for a tool that cannot open the element.** The tools list's `open` now says what a tool's element door does not open, `element_skips`, in the graph reader's words: `room`, `hidden`, `proposed`, `map_space` (a Map, Pin or Marker; a Zone is content) and `reading_aid`. Given the element as served, `openersFor` leaves out a row whose door skips a mark the element carries, each mark read by the readers `worldGraph` uses (`isRoomElement`, the hidden mark, `handsOnAsProposed`, the type, the reading aids), so the menu and the graph give one answer; a test holds the two equal on every element of the lens fixture's worlds. Without `element` every row is there, as before. A world's menu takes no element. Refused by name: an unknown options key, an element for a world's menu or naming another id than the address, a skip word outside the list's, and skips on a row with no element door. The shared openers fixture gains 25 cases (90 in all), the same bytes as the Python package's.
28
+ - **`mountWaymark` passes its `element` through**, so the Waymark's Open with rows follow the same rule with no change on the page.
29
+ - **`OwOpenersOptions`, `OwElementMark`**, and `OwToolOpen.element_skips`.
30
+
31
+ ### Changed
32
+
33
+ - **`TOOLS` repinned** at the tools list's 6da4d55: each row carries `element_skips` (Little Lens skips room, hidden, proposed and map space; Atlas and Lantern none until their doors are walked).
34
+
8
35
  ## [4.125.0] - 2026-11-01
9
36
 
10
37
  ### Added
@@ -318,7 +345,7 @@ earlier history lives in git log only.
318
345
 
319
346
  ### Added
320
347
 
321
- - **Sign in with OnlyWorlds from a native app** (RFC 8252). A tool registered as native lists a loopback return without a port (`http://127.0.0.1/<path>` or `http://[::1]/<path>`) or its own scheme (`obsidian://onlyworlds-signin`). `signInWithOnlyWorlds` now takes, beside an `https:` address, the loopback address with the port the app bound for this sign-in (`http://127.0.0.1:53682/onlyworlds-signin`, 1 to 65535, written plainly), which the server matches against the portless one, and a custom scheme exactly as registered (lower-case, not `http`, `https`, `javascript`, `data` or `file`, something after `://`). It refuses `localhost`, a loopback without its port, and on any form userinfo, a query, a fragment and a dot segment (and an `https:` address with an upper-case host or no path, which it took before), with a TypeError naming the forms it takes: the server would refuse each of them at authorize. Whether the tool is registered as native is the server's to check; the SDK does not read the client list. A native app opens the authorize URL in the system browser through `navigate`, and passes the address its loopback server or scheme handler received to `completeSignIn` as `url`.
348
+ - **Sign in with OnlyWorlds from a native app** (RFC 8252). A tool registered as native lists a loopback return without a port (`http://` and the IPv4 or the IPv6 loopback address with a path) or its own scheme (`obsidian://onlyworlds-signin`). `signInWithOnlyWorlds` now takes, beside an `https:` address, the loopback address with the port the app bound for this sign-in (the same form with a port from 1 to 65535, written plainly), which the server matches against the portless one, and a custom scheme exactly as registered (lower-case, not `http`, `https`, `javascript`, `data` or `file`, something after `://`). It refuses `localhost`, a loopback without its port, and on any form userinfo, a query, a fragment and a dot segment (and an `https:` address with an upper-case host or no path, which it took before), with a TypeError naming the forms it takes: the server would refuse each of them at authorize. Whether the tool is registered as native is the server's to check; the SDK does not read the client list. A native app opens the authorize URL in the system browser through `navigate`, and passes the address its loopback server or scheme handler received to `completeSignIn` as `url`.
322
349
 
323
350
  ### Fixed
324
351
 
package/README.md CHANGED
@@ -467,10 +467,12 @@ The rows of an "Open with" menu for a world or one of its elements: the site's p
467
467
  ```typescript
468
468
  import { openersFor, parseOwLink, TOOLS } from '@onlyworlds/sdk';
469
469
 
470
- const rows = openersFor(TOOLS, 'element', parseOwLink(link), { audience: 'member', signedIn: false, tool: 'mytool' });
470
+ const rows = openersFor(TOOLS, 'element', parseOwLink(link), { audience: 'member', signedIn: false, tool: 'mytool' }, { element });
471
471
  // [{ id: 'onlyworlds', name: 'onlyworlds.com', href, state: null }, { id: 'atlas', name: 'Atlas', href, state: 'Sign in to Atlas first' }, ...]
472
472
  ```
473
473
 
474
+ Pass the element as you were served it (`{ element }`): a tool whose element door does not open what it carries (a room element, a hidden or proposed one, a Map, Pin or Marker, a reading aid: the list's `open.element_skips`, each read as `worldGraph` reads it) has no row, rather than a link to a page that cannot open it. Without it, every row is there.
475
+
474
476
  `surface` says what the page knows and nothing is guessed: `audience` (`member` or `public`; the public sees only rows that need nothing first), `signedIn` (`null` when the page cannot know, and then no row says so), `browser` (false in a desktop app), `phone`, `online` (false with no connection: every row whose link is a web address then says "Needs a connection"), and `tool`, the page's own client name, whose row says "You are here". Draw the rows as given; the words are decided here, so every surface says the same.
475
477
 
476
478
  ### The Waymark: Open with, beside a name
package/SCHEMA.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OnlyWorlds Schema Reference
2
2
 
3
- **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.102** — canonical schema **00.33.00**, published 2026-11-01.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.0-dist.103** — canonical schema **00.34.00**, published 2026-11-02.
4
4
 
5
5
  GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
6
6
  Written for both humans and AI agents reading this package locally.
@@ -320,6 +320,7 @@ the group, the icon carries the type): blue · green · pink · amber.
320
320
  - `function` (text) — Main use, role, or purpose of the location within the world
321
321
  - `founding_date` (integer) — Date on which the location was founded, established, or designated
322
322
  - `parent_location` (single link → location) — Wider location that this location is part of
323
+ - `vehicle` (single link → object) — The Object this place is the inside of: a ship, a train, an airship, a walking city, a station that moves. Set it when the place moves with the thing; a place inside another place uses parent_location instead
323
324
  - `populations` (multi link → collective) — Distinct collective groups or communities residing within the location
324
325
 
325
326
  ### Politics
@@ -13,7 +13,7 @@ function refuseUnknownOptions(fn, opts, keys, after = "") {
13
13
 
14
14
  // src/v2/types.generated.ts
15
15
  var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
16
- var ONLYWORLDS_VERSION = "00.33.00";
16
+ var ONLYWORLDS_VERSION = "00.34.00";
17
17
  var ELEMENT_GROUPS = {
18
18
  ability: "amber",
19
19
  character: "blue",
@@ -143,7 +143,7 @@ var ELEMENT_SECTIONS = {
143
143
  { name: "World", order: 2, fields: ["author", "locations", "zones", "prohibitions", "adjudicators", "enforcers"] }
144
144
  ],
145
145
  location: [
146
- { name: "Setting", order: 1, fields: ["form", "function", "founding_date", "parent_location", "populations"] },
146
+ { name: "Setting", order: 1, fields: ["form", "function", "founding_date", "parent_location", "vehicle", "populations"] },
147
147
  { name: "Politics", order: 2, fields: ["political_climate", "primary_power", "governing_title", "secondary_powers", "zone", "rival", "partner"] },
148
148
  { name: "World", order: 3, fields: ["customs", "founders", "cults", "delicacies"] },
149
149
  { name: "Production", order: 4, fields: ["extraction_methods", "extraction_goods", "industry_methods", "industry_goods"] },
@@ -632,6 +632,7 @@ var FIELD_SCHEMA = {
632
632
  function: { type: "text" },
633
633
  founding_date: { type: "integer" },
634
634
  parent_location: { type: "single_link", target: "location" },
635
+ vehicle: { type: "single_link", target: "object" },
635
636
  populations: { type: "multi_link", target: "collective" },
636
637
  // Politics
637
638
  political_climate: { type: "text" },
@@ -1039,6 +1040,36 @@ function readingAidOf(element) {
1039
1040
  return AID_BY_KEY.get(`${fold(el.type)}/${fold(el.supertype)}`) ?? null;
1040
1041
  }
1041
1042
 
1043
+ // src/review.ts
1044
+ var PROPOSED_MARK = "x_review_proposed";
1045
+ var DAY = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
1046
+ function todayDay() {
1047
+ return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
1048
+ }
1049
+ function isPresent(v) {
1050
+ if (v === void 0 || v === null) return false;
1051
+ if (typeof v === "string") return trimWhiteSpace(v) !== "";
1052
+ if (Array.isArray(v)) return v.length > 0;
1053
+ if (typeof v === "object") return Object.keys(v).length > 0;
1054
+ return true;
1055
+ }
1056
+ function proposedMarkOf(element, today) {
1057
+ if (today !== void 0 && (typeof today !== "string" || !DAY.test(today))) {
1058
+ throw new TypeError(`proposedMarkOf: today is a day as YYYY-MM-DD; got ${JSON.stringify(today) ?? String(today)}.`);
1059
+ }
1060
+ if (!element || typeof element !== "object") return null;
1061
+ const v = element[PROPOSED_MARK];
1062
+ if (!isPresent(v) || typeof v !== "object" || Array.isArray(v)) return null;
1063
+ const m = v;
1064
+ const by = typeof m.by === "string" && trimWhiteSpace(m.by) ? trimWhiteSpace(m.by) : null;
1065
+ const expires = typeof m.expires === "string" && DAY.test(trimWhiteSpace(m.expires)) ? trimWhiteSpace(m.expires) : null;
1066
+ return { by, expires, lapsed: expires !== null && expires <= (today ?? todayDay()) };
1067
+ }
1068
+ function handsOnAsProposed(element) {
1069
+ if (!element || typeof element !== "object") return false;
1070
+ return isPresent(element[PROPOSED_MARK]);
1071
+ }
1072
+
1042
1073
  // src/names.ts
1043
1074
  var SLUGS = new Set(ELEMENT_TYPES);
1044
1075
  var OPTION_KEYS = ["supertype", "many"];
@@ -1233,7 +1264,24 @@ function parseOwLink(text) {
1233
1264
  return { form, world, worldIsSlug, type, id, lens, moment, canonical };
1234
1265
  }
1235
1266
 
1267
+ // src/marks.ts
1268
+ var ELEMENT_MARKS = ["room", "hidden", "proposed", "map_space", "reading_aid"];
1269
+ var MAP_SPACE = /* @__PURE__ */ new Set(["map", "pin", "marker"]);
1270
+ function isHiddenMark(el) {
1271
+ return el.hidden !== void 0 && el.hidden !== null && el.hidden !== false;
1272
+ }
1273
+ function marksOf(el) {
1274
+ const out = [];
1275
+ if (isRoomElement(el)) out.push("room");
1276
+ if (isHiddenMark(el)) out.push("hidden");
1277
+ if (handsOnAsProposed(el)) out.push("proposed");
1278
+ if (typeof el.type === "string" && MAP_SPACE.has(fold(el.type))) out.push("map_space");
1279
+ if (readingAidKey(el) !== null) out.push("reading_aid");
1280
+ return out;
1281
+ }
1282
+
1236
1283
  // src/openers.ts
1284
+ var OPTION_KEYS2 = ["element"];
1237
1285
  var SURFACE_KEYS = ["tool", "audience", "signedIn", "browser", "phone", "online"];
1238
1286
  var NEEDS = ["account", "device", null];
1239
1287
  var PLACEHOLDER = /\{(world|type|id)\}/g;
@@ -1252,7 +1300,7 @@ function templateOf(row, key, v) {
1252
1300
  if (NO_APP.includes(scheme)) fail(`tool ${row}: open.${key} is a ${scheme}: link, which opens no app`);
1253
1301
  return v;
1254
1302
  }
1255
- function openersFor(tools, kind, address, surface) {
1303
+ function openersFor(tools, kind, address, surface, options = {}) {
1256
1304
  if (!Array.isArray(tools)) fail("tools is the tools list's rows, an array");
1257
1305
  if (kind !== "world" && kind !== "element") fail(`kind is 'world' or 'element'; got ${JSON.stringify(kind)}`);
1258
1306
  if (address === null || typeof address !== "object" || Array.isArray(address)) {
@@ -1276,6 +1324,16 @@ function openersFor(tools, kind, address, surface) {
1276
1324
  if (typeof browser !== "boolean") fail("surface.browser is a boolean");
1277
1325
  if (typeof phone !== "boolean") fail("surface.phone is a boolean");
1278
1326
  if (typeof online !== "boolean") fail("surface.online is a boolean");
1327
+ if (options === null || typeof options !== "object" || Array.isArray(options)) fail("the options are an object ({ element })");
1328
+ refuseUnknownOptions("openersFor", options, OPTION_KEYS2);
1329
+ const element = options.element ?? null;
1330
+ if (element !== null) {
1331
+ if (typeof element !== "object" || Array.isArray(element)) fail("options.element is the element as served, an object, or null");
1332
+ if (kind !== "element") fail("options.element is for an element's menu; a world's menu takes none");
1333
+ const eid = element.id;
1334
+ if (typeof eid !== "string" || eid.toLowerCase() !== id) fail("options.element is the element the address names: its id differs");
1335
+ }
1336
+ const marks = element === null ? [] : marksOf(element);
1279
1337
  const values = { world, type, id };
1280
1338
  const fill = (template) => template.replace(PLACEHOLDER, (_, n) => values[n]);
1281
1339
  const offline = (href) => !online && WEB.test(href);
@@ -1294,10 +1352,16 @@ function openersFor(tools, kind, address, surface) {
1294
1352
  const elementDoor = templateOf(r.id, "element", o.element);
1295
1353
  const needs = o.needs === void 0 ? null : o.needs;
1296
1354
  if (!NEEDS.includes(needs)) fail(`tool ${r.id}: open.needs is 'account', 'device' or null; got ${JSON.stringify(needs)}`);
1355
+ const skips = o.element_skips === void 0 || o.element_skips === null ? [] : o.element_skips;
1356
+ if (!Array.isArray(skips) || skips.some((s) => !ELEMENT_MARKS.includes(s))) {
1357
+ fail(`tool ${r.id}: open.element_skips is a list of ${ELEMENT_MARKS.join(", ")}; got ${JSON.stringify(o.element_skips)}`);
1358
+ }
1359
+ if (elementDoor === null && skips.length > 0) fail(`tool ${r.id}: open.element_skips names what an element door leaves out, and the row has none`);
1297
1360
  if (r.rung !== "listed") continue;
1298
1361
  if (audience === "public" && needs !== null) continue;
1299
1362
  const template = kind === "element" ? elementDoor ?? worldDoor : worldDoor;
1300
1363
  if (template === null) continue;
1364
+ if (kind === "element" && marks.some((m) => skips.includes(m))) continue;
1301
1365
  const href = fill(template);
1302
1366
  let state = null;
1303
1367
  if (tool !== null && r.client === tool) state = "You are here";
@@ -1322,7 +1386,8 @@ var TOOLS = [
1322
1386
  "open": {
1323
1387
  "world": "https://atlas.onlyworlds.com/#/open/{world}",
1324
1388
  "element": "https://atlas.onlyworlds.com/#/open/{world}/element/{id}",
1325
- "needs": "account"
1389
+ "needs": "account",
1390
+ "element_skips": []
1326
1391
  }
1327
1392
  },
1328
1393
  {
@@ -1334,7 +1399,8 @@ var TOOLS = [
1334
1399
  "open": {
1335
1400
  "world": "https://lantern.onlyworlds.com/#/open/{world}",
1336
1401
  "element": "https://lantern.onlyworlds.com/#/open/{world}/element/{id}",
1337
- "needs": "account"
1402
+ "needs": "account",
1403
+ "element_skips": []
1338
1404
  }
1339
1405
  },
1340
1406
  {
@@ -1346,8 +1412,22 @@ var TOOLS = [
1346
1412
  "open": {
1347
1413
  "world": "https://little-lens.onlyworlds.com/#/open/{world}",
1348
1414
  "element": "https://little-lens.onlyworlds.com/#/open/{world}/element/{id}",
1349
- "needs": null
1415
+ "needs": null,
1416
+ "element_skips": [
1417
+ "room",
1418
+ "hidden",
1419
+ "proposed",
1420
+ "map_space"
1421
+ ]
1350
1422
  }
1423
+ },
1424
+ {
1425
+ "id": "tangle",
1426
+ "name": "Tactical Tangle",
1427
+ "url": "https://tangle.onlyworlds.com",
1428
+ "client": "tangle",
1429
+ "rung": "listed",
1430
+ "open": null
1351
1431
  }
1352
1432
  ];
1353
1433
 
@@ -1475,6 +1555,11 @@ export {
1475
1555
  readingAidKey,
1476
1556
  isCharterElement,
1477
1557
  readingAidOf,
1558
+ PROPOSED_MARK,
1559
+ proposedMarkOf,
1560
+ handsOnAsProposed,
1561
+ MAP_SPACE,
1562
+ isHiddenMark,
1478
1563
  typeWord,
1479
1564
  OwAddressError,
1480
1565
  elementAddress,
package/dist/index.d.ts CHANGED
@@ -48,7 +48,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
48
48
  declare const ELEMENT_TYPES: ElementType[];
49
49
  /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
50
50
  * distribution's VERSION file (see the provenance block at the top of this file). */
51
- declare const ONLYWORLDS_VERSION: "00.33.00";
51
+ declare const ONLYWORLDS_VERSION: "00.34.00";
52
52
  /** The four colour groups, named by their colour. A visual aid for drawing the 22 types,
53
53
  * not part of the standard: colour carries the group, ELEMENT_ICONS carries the type. */
54
54
  type ElementGroup = 'blue' | 'green' | 'pink' | 'amber';
@@ -160,8 +160,8 @@ type FieldType = 'text' | 'integer'
160
160
  * this repository. It was meant to surface the schema's `maximum:` constraint,
161
161
  * and that constraint is **advisory**: keel declares no `MaxValueValidator` and
162
162
  * the wire stores `charisma: 9999` against a `maximum: 100` field (201, verbatim).
163
- * The canonical schema walk therefore stays silent on bounds permanently, so
164
- * there is no source to wire this to and no promise it could keep. A public type
163
+ * The walk's schema.json carries the bounds as display data (a slider's range),
164
+ * never as a rule, so this type would promise what no field keeps. A public type
165
165
  * member meaning "hint the wire ignores" is one consumers read as validation.
166
166
  */
167
167
  | 'integer_max' | 'single_link' | 'multi_link';
@@ -1030,6 +1030,10 @@ declare const FIELD_SCHEMA: {
1030
1030
  readonly type: "single_link";
1031
1031
  readonly target: "location";
1032
1032
  };
1033
+ readonly vehicle: {
1034
+ readonly type: "single_link";
1035
+ readonly target: "object";
1036
+ };
1033
1037
  readonly populations: {
1034
1038
  readonly type: "multi_link";
1035
1039
  readonly target: "collective";
@@ -5658,6 +5662,55 @@ declare function degreeOf(graph: OwWorldGraph): Record<string, number>;
5658
5662
  */
5659
5663
  declare function outDegreeOf(graph: OwWorldGraph): Record<string, number>;
5660
5664
 
5665
+ /** Which part a door draws first: `gaps` under the size, `graph` at it and above. */
5666
+ type OwLandingMode = 'gaps' | 'graph';
5667
+ /** `heads` (default 5), `hops` (default 1) and `size` (default 24), each a whole number, 1 or more; null is the default. */
5668
+ interface OwLandingOptions {
5669
+ heads?: number | null;
5670
+ hops?: number | null;
5671
+ size?: number | null;
5672
+ }
5673
+ interface OwLandingMember {
5674
+ id: string;
5675
+ /** Steps from the head: 0 for the head itself. */
5676
+ hops: number;
5677
+ degree: number;
5678
+ }
5679
+ interface OwLandingCluster {
5680
+ head: string;
5681
+ /** The head first, then by hops, then by degree (highest first), then by id in code point order. */
5682
+ members: OwLandingMember[];
5683
+ }
5684
+ type OwLandingGapKind = 'orphan' | 'near_orphan' | 'no_place' | 'nobody_here';
5685
+ interface OwLandingGap {
5686
+ kind: OwLandingGapKind;
5687
+ id: string;
5688
+ }
5689
+ interface OwLanding {
5690
+ mode: OwLandingMode;
5691
+ /** The size the mode was read at. */
5692
+ size: number;
5693
+ clusters: OwLandingCluster[];
5694
+ /** Every node no head reaches within `hops`, by degree (highest first), then by id. */
5695
+ unclustered: {
5696
+ id: string;
5697
+ degree: number;
5698
+ }[];
5699
+ /** In the kinds' order (orphan, near_orphan, no_place, nobody_here), then by id; a node can carry several. */
5700
+ gaps: OwLandingGap[];
5701
+ }
5702
+ /**
5703
+ * A world's first picture at a door, from the graph `worldGraph` answered for the visitor, so it holds exactly what
5704
+ * that reader may see. The mode is `gaps` when the graph has fewer nodes than `size`, else `graph`; both parts are
5705
+ * always read. Heads: the Characters with an edge, most linked first (`degreeOf`'s count), ties by id in code point
5706
+ * order, at most `heads`, never a known-of node. A node within `hops` steps of a head (either way along an edge)
5707
+ * joins the nearest head, a tie going to the higher-ranked one. Gaps: the links report's orphans (degree 0) and
5708
+ * near-orphans (degree 1), a Character whose `location` names no Location node (`no_place`), a Location no
5709
+ * Character's `location` names (`nobody_here`); a known-of node is never a gap. The same graph and options give the
5710
+ * same answer, byte for byte. An unknown option, or one that is not a whole number of 1 or more, is refused by name.
5711
+ */
5712
+ declare function landingOf(graph: OwWorldGraph, options?: OwLandingOptions | null): OwLanding;
5713
+
5661
5714
  /** One word pair of a names map: `one` for a single thing, `many` for a plural (absent: `one`). */
5662
5715
  interface OwWordPair {
5663
5716
  one: string;
@@ -5750,6 +5803,14 @@ declare function elementAddress(address: OwAddress | OwAddressReading): string;
5750
5803
  */
5751
5804
  declare function parseOwLink(text: string): OwAddressReading;
5752
5805
 
5806
+ /** One reason a lore view leaves an element out, as the graph section names it. */
5807
+ type OwElementMark = 'room' | 'hidden' | 'proposed' | 'map_space' | 'reading_aid';
5808
+
5809
+ /** What `openersFor` takes beside the surface. */
5810
+ interface OwOpenersOptions {
5811
+ /** The element the menu is for, as the surface was served it (the API's body, the mark flat on it): a row whose door skips what it carries is not there. Absent or null: every row, as before 4.126.0. */
5812
+ element?: Record<string, unknown> | null;
5813
+ }
5753
5814
  /** What a person must have before a tool's link works: signed in to the tool (`account`), or the world already in the tool on this device (`device`). */
5754
5815
  type OwToolNeeds = 'account' | 'device';
5755
5816
  /** A tool's `open` in the tools list: its link templates and what they need first. */
@@ -5760,6 +5821,8 @@ interface OwToolOpen {
5760
5821
  element: string | null;
5761
5822
  /** What the person needs first; null for nothing, which is the one kind of row a public page offers. */
5762
5823
  needs: OwToolNeeds | null;
5824
+ /** What the element door does not open, in the graph section's words; [] or absent: it opens every element (a list older than the key has none). */
5825
+ element_skips?: readonly OwElementMark[];
5763
5826
  }
5764
5827
  /** The keys of one tools list row that `openersFor` reads; a row straight from `tools.json` carries more, and they are ignored. */
5765
5828
  interface OwTool {
@@ -5813,7 +5876,10 @@ interface OwOpener {
5813
5876
  * what `elementAddress` takes, with the world's id. A lens and a moment on it ride on no href.
5814
5877
  *
5815
5878
  * A row with `open: null`, or with no door for this kind, is not there. On an element, a tool with only
5816
- * a world door is a row to its world door that says "Opens the world". For the `public` audience only
5879
+ * a world door is a row to its world door that says "Opens the world". On an element given as
5880
+ * `options.element`, a row whose `open.element_skips` names a mark the element carries (room, hidden,
5881
+ * proposed, map space, a reading aid, each read as `worldGraph` reads it) is not there: its door cannot
5882
+ * open it. A world door alone opens the world, so it stays. For the `public` audience only
5817
5883
  * rows whose `open.needs` is null are there: a row that needs anything does not exist for the public.
5818
5884
  *
5819
5885
  * Each row's `state`, the first that holds: "You are here" for the surface's own tool (its `client` is
@@ -5830,10 +5896,11 @@ interface OwOpener {
5830
5896
  * and a slug or anything else for the world's id (`bad_world`); and an address without a world
5831
5897
  * (`no_world`), the text form inside a world included, since every row needs one. A TypeError names the
5832
5898
  * rest: a `kind` that is neither, an element's openers asked of an address with no element, an unknown
5833
- * key on the address or the surface, a missing or unknown `audience`, a surface value of the wrong type,
5834
- * a tools row that is not one (a `needs` outside the list's format included).
5899
+ * key on the address, the surface or the options, a missing or unknown `audience`, a surface value of the
5900
+ * wrong type, an element given for a world's menu or naming another element than the address, a tools row
5901
+ * that is not one (a `needs` or an `element_skips` word outside the list's format included).
5835
5902
  */
5836
- declare function openersFor(tools: readonly OwTool[], kind: OwOpenerKind, address: OwAddress | OwAddressReading, surface: OwOpenerSurface): OwOpener[];
5903
+ declare function openersFor(tools: readonly OwTool[], kind: OwOpenerKind, address: OwAddress | OwAddressReading, surface: OwOpenerSurface, options?: OwOpenersOptions): OwOpener[];
5837
5904
 
5838
5905
  /** The OnlyWorlds tools list's rows (format 1), in the list's order, as of this release: the keys openersFor reads. */
5839
5906
  declare const TOOLS: readonly OwTool[];
@@ -6993,4 +7060,4 @@ declare class TokenResource {
6993
7060
  getEncryptionInfo(): Promise<EncryptionInfo>;
6994
7061
  }
6995
7062
 
6996
- 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 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 OwLensCutReason, type OwLensMail, type OwLensOptions, type OwLensReader, type OwLensReading, type OwLensWorld, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, 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 OwPage, 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 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, lensesInUse, lookupWorld, 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 };
7063
+ 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 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 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 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, 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 };
package/dist/index.js CHANGED
@@ -9,11 +9,13 @@ import {
9
9
  FIELD_SCHEMA,
10
10
  GROUP_COLORS,
11
11
  GROUP_ORDER,
12
+ MAP_SPACE,
12
13
  MESSAGE_PAIR,
13
14
  MESSAGE_READ_MARK,
14
15
  NOTE_PAIR,
15
16
  ONLYWORLDS_VERSION,
16
17
  OwAddressError,
18
+ PROPOSED_MARK,
17
19
  PUBLIC_FIELDS,
18
20
  READING_AID_KEYS,
19
21
  REVIEW_PROPOSED_LABEL,
@@ -24,12 +26,15 @@ import {
24
26
  doorsOf,
25
27
  elementAddress,
26
28
  fold,
29
+ handsOnAsProposed,
27
30
  isAgentDoor,
28
31
  isCharterElement,
32
+ isHiddenMark,
29
33
  isKnownOf,
30
34
  isRoomElement,
31
35
  openersFor,
32
36
  parseOwLink,
37
+ proposedMarkOf,
33
38
  readingAidKey,
34
39
  readingAidOf,
35
40
  refuseUnknownOptions,
@@ -37,7 +42,7 @@ import {
37
42
  trimWhiteSpace,
38
43
  typeWord,
39
44
  unknownKey
40
- } from "./chunk-LSZNKRXL.js";
45
+ } from "./chunk-K7SQUXMR.js";
41
46
 
42
47
  // src/v2/keyed-id.ts
43
48
  var KEYED_IDS = "0199b6a0-6f0e-7c2a-9d1e-3b5c7a8e4f21";
@@ -2497,36 +2502,6 @@ function getElementLabel(elementType) {
2497
2502
  return ELEMENT_LABELS[elementType];
2498
2503
  }
2499
2504
 
2500
- // src/review.ts
2501
- var PROPOSED_MARK = "x_review_proposed";
2502
- var DAY = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
2503
- function todayDay() {
2504
- return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
2505
- }
2506
- function isPresent(v) {
2507
- if (v === void 0 || v === null) return false;
2508
- if (typeof v === "string") return trimWhiteSpace(v) !== "";
2509
- if (Array.isArray(v)) return v.length > 0;
2510
- if (typeof v === "object") return Object.keys(v).length > 0;
2511
- return true;
2512
- }
2513
- function proposedMarkOf(element, today) {
2514
- if (today !== void 0 && (typeof today !== "string" || !DAY.test(today))) {
2515
- throw new TypeError(`proposedMarkOf: today is a day as YYYY-MM-DD; got ${JSON.stringify(today) ?? String(today)}.`);
2516
- }
2517
- if (!element || typeof element !== "object") return null;
2518
- const v = element[PROPOSED_MARK];
2519
- if (!isPresent(v) || typeof v !== "object" || Array.isArray(v)) return null;
2520
- const m = v;
2521
- const by = typeof m.by === "string" && trimWhiteSpace(m.by) ? trimWhiteSpace(m.by) : null;
2522
- const expires = typeof m.expires === "string" && DAY.test(trimWhiteSpace(m.expires)) ? trimWhiteSpace(m.expires) : null;
2523
- return { by, expires, lapsed: expires !== null && expires <= (today ?? todayDay()) };
2524
- }
2525
- function handsOnAsProposed(element) {
2526
- if (!element || typeof element !== "object") return false;
2527
- return isPresent(element[PROPOSED_MARK]);
2528
- }
2529
-
2530
2505
  // src/message.ts
2531
2506
  var ADDRESSING_KEYS = ["keyless"];
2532
2507
  var isBody = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -2693,7 +2668,7 @@ function threadOf(messages, rootId) {
2693
2668
  };
2694
2669
  return inCreatedOrder(messages.filter((m) => isBody(m) && !isNote(m) && reaches(m)));
2695
2670
  }
2696
- var isHiddenMark = (value) => value !== void 0 && value !== null && value !== false;
2671
+ var isHiddenMark2 = (value) => value !== void 0 && value !== null && value !== false;
2697
2672
  function noteOf(narratives, characterId, members) {
2698
2673
  if (!Array.isArray(narratives) || typeof characterId !== "string" || characterId === "") return null;
2699
2674
  let line = null;
@@ -2703,7 +2678,7 @@ function noteOf(narratives, characterId, members) {
2703
2678
  const note = el;
2704
2679
  const id = idOf(note);
2705
2680
  if (typeof id !== "string" || id === "" || note.narrator !== characterId) continue;
2706
- if (isHiddenMark(note.hidden) || proposedMarkOf(note) !== null || !isOwnHand(note, characterId, members)) continue;
2681
+ if (isHiddenMark2(note.hidden) || proposedMarkOf(note) !== null || !isOwnHand(note, characterId, members)) continue;
2707
2682
  const key = timeKey(note.created_at);
2708
2683
  if (line === null || (key !== null ? lineKey === null || compareKeys(key, lineKey) >= 0 : lineKey === null)) {
2709
2684
  line = id;
@@ -2927,8 +2902,9 @@ var Reading = class {
2927
2902
  /** The ids a body this reader is served may link to: the view, and the proposed elements its rung sees (keel's `scoped` leaves them out for the public rung alone). */
2928
2903
  this.linkable = /* @__PURE__ */ new Set();
2929
2904
  this.served = /* @__PURE__ */ new Map();
2930
- this.inView = /* @__PURE__ */ new Map();
2931
- this.inFull = /* @__PURE__ */ new Map();
2905
+ /** Who links to each element, in the reader's view and in the owner's world: built on the first hop that asks,
2906
+ * since a reading with no lens (a graph, a menu's marks) never reads it. Everything it reads is set by the constructor. */
2907
+ this.incoming = null;
2932
2908
  const hidden = this.hidden;
2933
2909
  if (Array.isArray(world.hidden)) {
2934
2910
  for (const id of world.hidden) if (typeof id === "string") hidden.add(id);
@@ -2940,7 +2916,7 @@ var Reading = class {
2940
2916
  this.byId.set(el.id, el);
2941
2917
  this.typeOf.set(el.id, type);
2942
2918
  this.order.push(el.id);
2943
- if (el.hidden !== void 0 && el.hidden !== null && el.hidden !== false) hidden.add(el.id);
2919
+ if (isHiddenMark(el)) hidden.add(el.id);
2944
2920
  if (isRoomElement(el)) this.room.add(el.id);
2945
2921
  const aid = readingAidKey(el);
2946
2922
  if (aid !== null) this.aid.set(el.id, aid);
@@ -2981,18 +2957,26 @@ var Reading = class {
2981
2957
  }
2982
2958
  this.members = Array.isArray(world.members) ? world.members : null;
2983
2959
  this.asOf = asOf;
2960
+ }
2961
+ /** The reverse links, built once on first ask. */
2962
+ linkedFrom() {
2963
+ if (this.incoming !== null) return this.incoming;
2964
+ const view = /* @__PURE__ */ new Map();
2965
+ const full = /* @__PURE__ */ new Map();
2984
2966
  for (const id of this.order) {
2985
2967
  for (const t of this.fullLinks(id)) {
2986
2968
  if (!this.byId.has(t)) continue;
2987
- if (!this.inFull.has(t)) this.inFull.set(t, []);
2988
- this.inFull.get(t).push(id);
2969
+ if (!full.has(t)) full.set(t, []);
2970
+ full.get(t).push(id);
2989
2971
  }
2990
2972
  if (!this.view.has(id)) continue;
2991
2973
  for (const t of this.links(id)) {
2992
- if (!this.inView.has(t)) this.inView.set(t, []);
2993
- this.inView.get(t).push(id);
2974
+ if (!view.has(t)) view.set(t, []);
2975
+ view.get(t).push(id);
2994
2976
  }
2995
2977
  }
2978
+ this.incoming = { view, full };
2979
+ return this.incoming;
2996
2980
  }
2997
2981
  /**
2998
2982
  * The ids the element's owner-served body links to, in the schema's field order. A link reaches only an
@@ -3107,7 +3091,7 @@ var Reading = class {
3107
3091
  const landed = /* @__PURE__ */ new Set();
3108
3092
  for (const f of from) {
3109
3093
  if (this.stubs.has(f) || this.room.has(f) || stops !== void 0 && stops(f)) continue;
3110
- for (const t of [...this.links(f), ...this.inView.get(f) ?? []]) if (!excluded(t)) landed.add(t);
3094
+ for (const t of [...this.links(f), ...this.linkedFrom().view.get(f) ?? []]) if (!excluded(t)) landed.add(t);
3111
3095
  }
3112
3096
  const reached = new Set(landed);
3113
3097
  const edges = [];
@@ -3127,7 +3111,7 @@ var Reading = class {
3127
3111
  for (const f of from) {
3128
3112
  if (this.stubs.has(f) || this.room.has(f)) continue;
3129
3113
  for (const t of this.fullLinks(f)) consider(t);
3130
- for (const t of this.inFull.get(f) ?? []) consider(t);
3114
+ for (const t of this.linkedFrom().full.get(f) ?? []) consider(t);
3131
3115
  }
3132
3116
  for (const r of landedRelations) for (const t of this.fullLinks(r)) consider(t);
3133
3117
  return out;
@@ -3552,7 +3536,7 @@ function isInstant(s) {
3552
3536
  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][mo - 1];
3553
3537
  return days !== void 0 && d >= 1 && d <= days && h <= 23 && mi <= 59 && se <= 59 && y >= 1;
3554
3538
  }
3555
- var proposed = (el) => el.x_review_proposed !== void 0 && el.x_review_proposed !== null;
3539
+ var proposed = (el) => proposedMarkOf(el) !== null;
3556
3540
  function recordMarkOf(element) {
3557
3541
  if (!isObject(element) || element.type !== "event") return null;
3558
3542
  const m = element[RECORD_FIELD];
@@ -3577,7 +3561,7 @@ function recordsOf(characterId, elements) {
3577
3561
  if (!Array.isArray(elements)) throw new TypeError("recordsOf: elements must be an array");
3578
3562
  const storiesOf = /* @__PURE__ */ new Map();
3579
3563
  for (const n of elements) {
3580
- if (!isObject(n) || n.type !== "narrative" || proposed(n)) continue;
3564
+ if (!isObject(n) || n.type !== "narrative" || !isString(n.id) || proposed(n)) continue;
3581
3565
  const p = n.protagonist === characterId;
3582
3566
  const r = n.narrator === characterId;
3583
3567
  if (!p && !r) continue;
@@ -3591,7 +3575,7 @@ function recordsOf(characterId, elements) {
3591
3575
  const out = [];
3592
3576
  for (const ev of elements) {
3593
3577
  const mark = recordMarkOf(ev);
3594
- if (!mark || proposed(ev) || !list(ev.characters).includes(characterId)) continue;
3578
+ if (!mark || !isString(ev.id) || proposed(ev) || !list(ev.characters).includes(characterId)) continue;
3595
3579
  const id = ev.id;
3596
3580
  const stories = (storiesOf.get(id) ?? []).map((s) => ({ ...s }));
3597
3581
  stories.sort((a, b) => cp(a.id, b.id));
@@ -3614,7 +3598,6 @@ function recordsOf(characterId, elements) {
3614
3598
  // src/graph.ts
3615
3599
  var GRAPH_OPTION_KEYS = ["lens", "asOf", "clock", "rooms", "hidden", "proposed", "mapSpace"];
3616
3600
  var DECLARED_LINKS = ["x_lens_leads_to", "x_spine_depends_on"];
3617
- var MAP_SPACE = /* @__PURE__ */ new Set(["map", "pin", "marker"]);
3618
3601
  var GRAPH_REASONS = [...CUT_REASONS, "room", "hidden", "proposed", "map_space", "reading_aid", "outside_lens"];
3619
3602
  var GRAPH_OWNER_ONLY = /* @__PURE__ */ new Set([...OWNER_ONLY, "hidden", "proposed"]);
3620
3603
  function flag(opts, key) {
@@ -3772,6 +3755,94 @@ function outDegreeOf(graph) {
3772
3755
  return Object.fromEntries([...targets].map(([id, t]) => [id, t.size]));
3773
3756
  }
3774
3757
 
3758
+ // src/landing.ts
3759
+ var OPTION_KEYS = ["heads", "hops", "size"];
3760
+ var GAP_ORDER = ["orphan", "near_orphan", "no_place", "nobody_here"];
3761
+ function whole2(opts, key, fallback) {
3762
+ const v = valueOf(opts, key);
3763
+ if (v === null) return fallback;
3764
+ if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
3765
+ throw new RangeError(`landingOf: ${key} is a whole number, 1 or more; got ${JSON.stringify(v) ?? typeof v}.`);
3766
+ }
3767
+ return v;
3768
+ }
3769
+ function landingOf(graph, options) {
3770
+ if (!isBody2(graph) || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
3771
+ throw new TypeError("landingOf: graph is what worldGraph answers, an object with nodes and edges lists.");
3772
+ }
3773
+ if (options !== void 0 && options !== null && !isBody2(options)) {
3774
+ throw new TypeError(`landingOf: options is an object, such as { heads: 5 }; got ${JSON.stringify(options) ?? typeof options}.`);
3775
+ }
3776
+ refuseUnknownOptions("landingOf", options, OPTION_KEYS);
3777
+ const opts = isBody2(options) ? options : {};
3778
+ const k = whole2(opts, "heads", 5);
3779
+ const reach = whole2(opts, "hops", 1);
3780
+ const size = whole2(opts, "size", 24);
3781
+ const degree = new Map(graph.nodes.map((n) => [n.id, 0]));
3782
+ const near = new Map(graph.nodes.map((n) => [n.id, /* @__PURE__ */ new Set()]));
3783
+ const type = new Map(graph.nodes.map((n) => [n.id, n.type]));
3784
+ const add = (id) => {
3785
+ const d = degree.get(id);
3786
+ if (d !== void 0) degree.set(id, d + 1);
3787
+ };
3788
+ const placed = /* @__PURE__ */ new Set();
3789
+ const inhabited = /* @__PURE__ */ new Set();
3790
+ for (const e of graph.edges) {
3791
+ add(e.source);
3792
+ if (e.target !== e.source) add(e.target);
3793
+ if (e.target !== e.source && near.has(e.source) && near.has(e.target)) {
3794
+ near.get(e.source).add(e.target);
3795
+ near.get(e.target).add(e.source);
3796
+ }
3797
+ if (e.field === "location" && type.get(e.source) === "character" && type.get(e.target) === "location") {
3798
+ placed.add(e.source);
3799
+ inhabited.add(e.target);
3800
+ }
3801
+ }
3802
+ const deg = (id) => degree.get(id) ?? 0;
3803
+ const heads = graph.nodes.filter((n) => n.type === "character" && n.known_of !== true && deg(n.id) > 0).map((n) => n.id).sort((a, b) => deg(b) - deg(a) || byCodePoint(a, b)).slice(0, k);
3804
+ const best = /* @__PURE__ */ new Map();
3805
+ heads.forEach((head, rank) => {
3806
+ const seen = /* @__PURE__ */ new Map([[head, 0]]);
3807
+ let frontier = [head];
3808
+ for (let step = 0; step < reach && frontier.length; step++) {
3809
+ const next = [];
3810
+ for (const id of frontier) {
3811
+ for (const nb of near.get(id) ?? []) {
3812
+ if (seen.has(nb)) continue;
3813
+ seen.set(nb, step + 1);
3814
+ next.push(nb);
3815
+ }
3816
+ }
3817
+ frontier = next;
3818
+ }
3819
+ for (const [id, hops] of seen) {
3820
+ const b = best.get(id);
3821
+ if (!b || hops < b.hops || hops === b.hops && rank < b.rank) best.set(id, { hops, rank });
3822
+ }
3823
+ });
3824
+ const clusters = heads.map((head) => ({ head, members: [] }));
3825
+ const unclustered = [];
3826
+ for (const n of graph.nodes) {
3827
+ const b = best.get(n.id);
3828
+ if (b) clusters[b.rank].members.push({ id: n.id, hops: b.hops, degree: deg(n.id) });
3829
+ else unclustered.push({ id: n.id, degree: deg(n.id) });
3830
+ }
3831
+ for (const c of clusters) c.members.sort((a, b) => a.hops - b.hops || b.degree - a.degree || byCodePoint(a.id, b.id));
3832
+ unclustered.sort((a, b) => b.degree - a.degree || byCodePoint(a.id, b.id));
3833
+ const gaps = [];
3834
+ for (const n of graph.nodes) {
3835
+ if (n.known_of === true) continue;
3836
+ const d = deg(n.id);
3837
+ if (d === 0) gaps.push({ kind: "orphan", id: n.id });
3838
+ if (d === 1) gaps.push({ kind: "near_orphan", id: n.id });
3839
+ if (n.type === "character" && !placed.has(n.id)) gaps.push({ kind: "no_place", id: n.id });
3840
+ if (n.type === "location" && !inhabited.has(n.id)) gaps.push({ kind: "nobody_here", id: n.id });
3841
+ }
3842
+ gaps.sort((a, b) => GAP_ORDER.indexOf(a.kind) - GAP_ORDER.indexOf(b.kind) || byCodePoint(a.id, b.id));
3843
+ return { mode: graph.nodes.length < size ? "gaps" : "graph", size, clusters, unclustered, gaps };
3844
+ }
3845
+
3775
3846
  // src/drag.ts
3776
3847
  var TYPES = new Set(ELEMENT_TYPES);
3777
3848
  function dragField(a, b) {
@@ -5560,8 +5631,8 @@ var DEFAULT_FORMAT_PLAIN = "{year} {era}";
5560
5631
  var DEFAULT_FORMAT_INTERCALARY = "{intercalary}, {year} {era}";
5561
5632
  var EMPTY_KNOWN = "\uE000";
5562
5633
  function renderTemplate(template, values) {
5563
- let out = template.replace(/\{([a-z_]+)\}/g, (whole2, token) => {
5564
- if (!KNOWN_TOKENS.includes(token)) return whole2;
5634
+ let out = template.replace(/\{([a-z_]+)\}/g, (whole3, token) => {
5635
+ if (!KNOWN_TOKENS.includes(token)) return whole3;
5565
5636
  const v = values[token];
5566
5637
  return v == null || v === "" ? EMPTY_KNOWN : v;
5567
5638
  });
@@ -6074,6 +6145,7 @@ export {
6074
6145
  isTemplate,
6075
6146
  isToEveryone,
6076
6147
  kindCanWrite,
6148
+ landingOf,
6077
6149
  lensesInUse,
6078
6150
  lookupWorld,
6079
6151
  monthStartSteps,
package/dist/waymark.d.ts CHANGED
@@ -1,3 +1,6 @@
1
+ /** One reason a lore view leaves an element out, as the graph section names it. */
2
+ type OwElementMark = 'room' | 'hidden' | 'proposed' | 'map_space' | 'reading_aid';
3
+
1
4
  /** What a person must have before a tool's link works: signed in to the tool (`account`), or the world already in the tool on this device (`device`). */
2
5
  type OwToolNeeds = 'account' | 'device';
3
6
  /** A tool's `open` in the tools list: its link templates and what they need first. */
@@ -8,6 +11,8 @@ interface OwToolOpen {
8
11
  element: string | null;
9
12
  /** What the person needs first; null for nothing, which is the one kind of row a public page offers. */
10
13
  needs: OwToolNeeds | null;
14
+ /** What the element door does not open, in the graph section's words; [] or absent: it opens every element (a list older than the key has none). */
15
+ element_skips?: readonly OwElementMark[];
11
16
  }
12
17
  /** The keys of one tools list row that `openersFor` reads; a row straight from `tools.json` carries more, and they are ignored. */
13
18
  interface OwTool {
package/dist/waymark.js CHANGED
@@ -6,7 +6,7 @@ import {
6
6
  openersFor,
7
7
  refuseUnknownOptions,
8
8
  typeWord
9
- } from "./chunk-LSZNKRXL.js";
9
+ } from "./chunk-K7SQUXMR.js";
10
10
 
11
11
  // src/waymark/glyphs.ts
12
12
  var MARK_PATH = "M48.8 0.0 43.8 0.4 39.0 1.2 36.0 2.0 33.2 2.9 29.3 4.5 24.8 6.8 20.6 9.5 17.0 12.4 13.6 15.7 10.4 19.4 7.8 23.1 5.8 26.6 4.5 29.3 3.3 32.1 1.8 36.8 0.8 41.2 0.1 46.3 0.0 51.1 0.4 56.2 1.2 61.0 2.0 63.9 2.9 66.8 4.5 70.7 6.8 75.2 9.5 79.4 12.4 82.9 15.7 86.3 19.4 89.5 23.1 92.1 26.6 94.2 29.3 95.5 32.1 96.7 36.8 98.2 41.2 99.2 46.3 99.8 51.1 100.0 56.2 99.6 61.0 98.8 63.9 98.0 66.8 97.1 70.7 95.5 75.2 93.2 79.4 90.4 82.9 87.6 86.3 84.3 89.5 80.5 92.1 76.9 94.2 73.4 95.5 70.7 96.7 67.9 98.2 63.2 99.2 58.7 99.8 53.7 100.0 48.8 99.6 43.8 98.6 38.4 97.1 33.2 95.5 29.3 93.2 24.8 90.4 20.6 87.6 17.0 84.3 13.6 80.5 10.4 76.9 7.8 73.4 5.8 70.7 4.5 67.9 3.3 63.2 1.8 58.7 0.8 53.7 0.1ZM77.5 80.7 74.1 83.4 70.7 85.7 67.0 87.5 64.5 88.6 64.1 88.7 65.7 86.3 67.1 83.9 68.7 80.7 69.9 77.6 72.7 78.5 73.0 78.4ZM22.5 80.7 25.6 79.0 27.3 78.3 30.0 77.6 31.3 80.7 32.8 83.9 34.2 86.3 35.9 88.7 32.9 87.5 29.3 85.7 25.8 83.4ZM51.2 74.5 55.1 74.7 59.9 75.2 64.2 76.0 67.5 76.9 66.0 80.5 64.2 84.0 62.0 87.4 59.6 90.1 55.1 90.9 52.2 91.2 51.2 91.1ZM48.7 74.5 48.8 91.1 47.7 91.2 44.9 90.9 40.3 90.1 38.2 87.8 36.3 85.0 34.2 81.2 32.5 77.0 35.8 76.0 40.5 75.2 44.5 74.7ZM91.1 51.2 91.1 52.9 90.8 56.3 90.1 59.7 89.3 62.5 88.5 64.8 87.2 67.7 85.7 70.7 83.9 73.4 82.0 75.9 79.4 78.9 76.3 77.2 73.8 76.1 76.2 68.8 77.8 62.7 78.7 56.8 79.0 51.2ZM55.8 51.2 67.7 51.2 67.6 55.1 67.2 59.0 66.7 61.5 65.7 65.0 61.0 64.2 55.7 63.6ZM32.5 51.2 44.5 51.2 44.4 63.6 39.7 64.1 34.5 65.0 33.5 61.3 32.9 58.1 32.5 54.2ZM8.8 51.2 21.0 51.2 21.0 53.3 21.4 56.6 22.7 64.0 23.8 68.4 25.0 72.1 26.6 75.9 23.7 77.2 20.6 78.9 18.5 76.7 16.5 74.1 14.8 71.5 13.4 69.1 12.1 66.3 11.0 63.6 10.1 60.5 9.4 57.3 8.9 53.5 8.8 51.3ZM36.2 27.0 39.5 27.5 44.5 28.2 44.4 48.8 32.4 48.7 32.8 44.5 33.6 39.1 35.0 32.0ZM63.9 26.9 65.2 32.1 66.6 39.2 67.4 44.8 67.7 48.7 55.8 48.8 55.7 28.1 60.5 27.5ZM74.8 23.4 76.9 22.5 79.4 21.1 82.0 24.0 84.8 27.8 86.2 30.3 87.5 32.9 88.6 35.4 89.5 38.1 90.3 41.2 90.8 44.0 91.1 47.0 91.1 48.8 79.0 48.7 78.7 44.6 78.0 39.3 76.5 31.2 74.7 23.5ZM25.5 23.5 25.5 23.7 24.5 26.8 23.7 30.2 22.4 36.6 21.5 42.5 21.1 48.7 8.8 48.8 8.8 47.0 9.2 43.7 9.8 40.8 10.5 38.1 11.5 35.2 12.4 32.9 13.8 30.2 15.2 27.8 17.9 24.0 20.6 21.1 23.1 22.5ZM64.1 11.3 67.0 12.4 70.7 14.3 74.1 16.5 77.5 19.3 75.6 20.3 73.2 21.5 70.0 22.6 68.7 19.2 67.1 16.1 65.7 13.6ZM35.9 11.3 34.2 13.6 32.8 16.1 31.3 19.2 30.0 22.5 27.9 21.9 26.4 21.3 22.5 19.3 25.8 16.5 29.3 14.3 32.9 12.4 35.4 11.4ZM51.2 8.8 52.2 8.8 55.1 9.0 59.6 9.9 61.7 12.2 64.2 16.0 66.0 19.5 67.6 23.3 64.3 24.3 59.4 25.2 56.2 25.6 51.2 25.5ZM48.8 8.8 48.7 25.5 44.2 25.6 40.6 25.2 36.4 24.5 32.4 23.2 33.9 19.5 35.7 16.0 38.2 12.2 40.3 9.9 44.9 9.0 47.7 8.8Z";
@@ -110,7 +110,7 @@ function mountWaymark(target, options) {
110
110
  const isPublic = reader === "public";
111
111
  const kind = element === null ? "world" : "element";
112
112
  const address = element === null ? { form: "human", world: world.id } : { form: "human", world: world.id, type: element.type, id: element.id };
113
- const rowsFor = (online) => openersFor(tools, kind, address, { tool, audience: isPublic ? "public" : "member", signedIn, browser, phone, online });
113
+ const rowsFor = (online) => openersFor(tools, kind, address, { tool, audience: isPublic ? "public" : "member", signedIn, browser, phone, online }, { element });
114
114
  const rowsOnline = rowsFor(true);
115
115
  const rowsOffline = rowsFor(false);
116
116
  const throughLenses = isPublic ? [] : [...lenses ?? []];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.125.0",
3
+ "version": "4.127.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {