@onlyworlds/sdk 4.116.1 → 4.117.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/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.96** (canonical 00.33.00).
3
+ **Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.97** (canonical 00.33.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
 
package/CHANGELOG.md CHANGED
@@ -5,6 +5,21 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.117.1] - 2026-10-30
9
+
10
+ ### Changed
11
+
12
+ - **The schema pin moves to schema-dist serial 97** (`v0.33.0-dist.97`), which states in the address profile that a writer's empty string is never absent and cases it four times, once per part. `elementAddress` already answered that way, so no code changes: given `""` for the world, the type, the id or the lens it throws `OwAddressError` with that part's own reason (`bad_world`, `unknown_type`, `bad_id`, `bad_lens`); only `null` or a missing key counts as absent.
13
+
14
+ ## [4.117.0] - 2026-10-30
15
+
16
+ ### Changed
17
+
18
+ - **The Waymark's Escape stops at the component.** Every Escape the fan-out handles (in the fan-out, on the mark or the "Open with" entry while it is open, and in the toast after a failed copy) calls `stopPropagation()` beside `preventDefault()`, so a page's own Escape listener (one on `document` that leaves the page, say) does not also run. An Escape while the fan-out is closed reaches the page as before.
19
+ - **The fan-out picks its side when it opens.** At each open it measures itself against the box that clips it on each axis: the nearest ancestor of the name whose `overflow` on that axis is not `visible`, within the window, else the window. When the fan-out at the name's start would cross that box's right edge it opens at the name's end (`ow-waymark__pop--end`), and when below the name would cross its bottom it opens above (`ow-waymark__pop--up`), each only where that side crosses less. The toast shares the anchor and takes the same side (`ow-waymark__toast--end`, `ow-waymark__toast--up`); after a failed copy with the fan-out above the name, the toast sits below it. The fan-out's classes are removed when it closes, and the toast's when it hides. Where the fan-out is a sheet from the bottom, no side is chosen. The rules are in `waymark.css`, with no new colour, and still no node carries a style attribute.
20
+ - **The sheet from the bottom starts at 480 px wide and below** (it was 390 px), so every portrait phone, which runs to about 430 px, gets the sheet with its rows at least 44 px tall rather than the popover; a desktop window 480 px wide or narrower gets it too, by width alone.
21
+ - **The page's own row leads nowhere.** The row `openersFor` gives "You are here" (the `tool` option's own) is a button with `aria-current="page"` and no link, in its place in the arrow order and with the same look; pressing it closes the fan-out and returns focus to what opened it. Every other row is a link as before.
22
+
8
23
  ## [4.116.1] - 2026-10-30
9
24
 
10
25
  ### Changed
package/README.md CHANGED
@@ -491,13 +491,13 @@ const dispose = mountWaymark(document.querySelector('h1.name'), {
491
491
  // later: dispose() removes every node, listener and timer it added
492
492
  ```
493
493
 
494
- What it draws is decided in the core, never in the component: the rows and their words are `openersFor`'s, a member's "Last shaped in Atlas, 12 Oct" line is `doorsOf`'s newest entry in `doorWhere`'s words with its date, and Copy link copies `elementAddress`'s site address with the world's id (never a slug) and says "Link copied". When the page has no clipboard or the copy is refused, the fan-out stays open and the toast says "Could not copy the link." over the same address in a read-only line, selected for a copy by hand; it stays until the fan-out closes or Escape. The public face (`reader: 'public'`) shows the name and type, only the rows that need nothing first, and Copy link: no last door, no lenses. A row that cannot open now says why ("Sign in to Atlas first", "Needs the world on this phone") and is grey; grey means nothing else. The page's own tool says "You are here".
494
+ What it draws is decided in the core, never in the component: the rows and their words are `openersFor`'s, a member's "Last shaped in Atlas, 12 Oct" line is `doorsOf`'s newest entry in `doorWhere`'s words with its date, and Copy link copies `elementAddress`'s site address with the world's id (never a slug) and says "Link copied". When the page has no clipboard or the copy is refused, the fan-out stays open and the toast says "Could not copy the link." over the same address in a read-only line, selected for a copy by hand; it stays until the fan-out closes or Escape. The public face (`reader: 'public'`) shows the name and type, only the rows that need nothing first, and Copy link: no last door, no lenses. A row that cannot open now says why ("Sign in to Atlas first", "Needs the world on this phone") and is grey; grey means nothing else. The page's own tool says "You are here", and its row leads nowhere: a button with `aria-current="page"`, not a link, which closes the fan-out and returns focus to what opened it.
495
495
 
496
496
  Options, each refused by name when unknown, before anything is drawn: `world` (its `x_names`, when present, words the type), `element`, `reader`, `tool`, `signedIn`, `browser`, `phone`, `tools` (default `TOOLS`), `lenses` (`[{ id, name }]`, the Through row; absent, no row; a lens chosen rides on the copied link as `?lens=`), `ground`, `entry` and `returnFocus`.
497
497
 
498
498
  **No inline style.** The component sets no `style` attribute and never touches `element.style`, so it runs under `style-src 'self'`; bundle `waymark.css` with the page. Every colour in it is one of the Waymark's two grounds, declared once at the top of the file.
499
499
 
500
- **Keyboard and small screens.** The mark is a button and the fan-out a menu: Tab goes from the mark through the rows in order, the arrow keys, Home and End move between rows, Escape closes it and returns focus to what opened it. Focus moving out of it (Tab off the last row, Shift+Tab off the first, a click elsewhere) closes it too, and focus stays where it was moved; off the last row at the end of the page, where focus lands on the page itself, as well. The window losing focus (switching to another app) leaves it open. At 390 px wide and below it is a sheet from the bottom, its rows at least 44 px tall; the mark's tap area is at least 44 by 44 px at every width, without moving the glyph.
500
+ **Keyboard and small screens.** The mark is a button and the fan-out a menu: Tab goes from the mark through the rows in order, the arrow keys, Home and End move between rows, Escape closes it and returns focus to what opened it, and stops there: every Escape the fan-out handles calls `stopPropagation()`, so a page's own Escape listener does not also run (an Escape while it is closed is the page's). Focus moving out of it (Tab off the last row, Shift+Tab off the first, a click elsewhere) closes it too, and focus stays where it was moved; off the last row at the end of the page, where focus lands on the page itself, as well. The window losing focus (switching to another app) leaves it open. It opens below the name at its start; at each open it measures itself against the box that clips it (the nearest ancestor whose `overflow` on that axis is not `visible`, else the window) and opens at the name's end (`ow-waymark__pop--end`) when the start would cross that box's right edge, or above the name (`ow-waymark__pop--up`) when below would cross its bottom, and the toast takes the same side. At 480 px wide and below it is a sheet from the bottom, with no side chosen, its rows at least 44 px tall: every portrait phone (they run to about 430 px) and a desktop window as narrow, by width alone; the mark's tap area is at least 44 by 44 px at every width, without moving the glyph.
501
501
 
502
502
  **The ways in, one setting.** `entry: 'mark'` draws the mark beside the name as the button that opens the fan-out. `entry: 'menu'` draws no mark and gives back an "Open with" entry for the page's own "..." menu, as `dispose.entry` (a button; put it in the menu, and the disposer takes it out again), which opens the same fan-out. `entry: 'both'` draws the mark and gives the entry. Escape returns focus to the one that opened the fan-out: the mark, or for the entry `returnFocus`, the page's own element to take focus back (its "..." button, which stays visible when its menu closes), else the entry itself. `returnFocus` is refused with `entry: 'mark'` and when it is not an HTMLElement. The default is `'mark'`; which way in is the default for everyone waits on a round with people who have never seen the tools, so a surface that sets `entry` explicitly is unaffected when it changes.
503
503
 
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.96** — canonical schema **00.33.00**, published 2026-10-30.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.97** — canonical schema **00.33.00**, published 2026-10-30.
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.
package/dist/waymark.css CHANGED
@@ -290,6 +290,26 @@
290
290
  top: auto;
291
291
  bottom: calc(100% + 6px);
292
292
  }
293
+ /* The side the fan-out took when it opened, measured against the box that clips it (the nearest
294
+ ancestor that clips, else the window): at the name's end when the start would cross that box's right
295
+ edge, above the name when below would cross its bottom. The toast shares the anchor and the side. No
296
+ side is chosen while the fan-out is the sheet below (a fixed pop), and the sheet, later in this file,
297
+ sets all four of the pop's sides. */
298
+ .ow-waymark__pop--end,
299
+ .ow-waymark__toast--end {
300
+ right: 0;
301
+ left: auto;
302
+ }
303
+ .ow-waymark__pop--up,
304
+ .ow-waymark__toast--up {
305
+ top: auto;
306
+ bottom: calc(100% + 6px);
307
+ }
308
+ /* While the fan-out is open above the name (a failed copy), the toast sits below it, clear of it. */
309
+ .ow-waymark__pop--up:not([hidden]) ~ .ow-waymark__toast {
310
+ top: calc(100% + 6px);
311
+ bottom: auto;
312
+ }
293
313
  /* The address after a failed copy: read-only, selected whole by one click. */
294
314
  .ow-waymark__address {
295
315
  box-sizing: border-box;
@@ -308,8 +328,10 @@
308
328
  outline-offset: 1px;
309
329
  }
310
330
 
311
- /* 390 px wide and below: a sheet from the bottom, the page behind dimmed, rows tall enough to touch. */
312
- @media (max-width: 390px) {
331
+ /* 480 px wide and below: a sheet from the bottom, the page behind dimmed, rows tall enough to touch.
332
+ Portrait phones run to about 430 px, so every one gets the sheet with room to spare, and so does a
333
+ desktop window as narrow: by width alone, whatever the pointer. */
334
+ @media (max-width: 480px) {
313
335
  .ow-waymark__scrim {
314
336
  display: block;
315
337
  position: fixed;
package/dist/waymark.d.ts CHANGED
@@ -85,11 +85,23 @@ interface OwWaymark {
85
85
  * "Could not copy the link." over the address, selected in a read-only line to copy by hand, until the
86
86
  * fan-out closes. Focus moving out of the fan-out closes it and stays where it was moved.
87
87
  *
88
+ * The surface's own row (the `tool` option's, "You are here") leads nowhere: a button with
89
+ * `aria-current="page"` and no link, which closes the fan-out and returns focus to what opened it.
90
+ *
88
91
  * Keyboard: the mark is a button and the fan-out a menu; Tab goes from the mark through the rows in
89
92
  * order, the arrow keys, Home and End move within it, Escape closes it and returns focus to what opened
90
93
  * it: the mark, or for the entry `returnFocus` when given (the surface's "..." button, which stays
91
- * visible when its menu closes), else the entry. A click outside closes it. At 390 px wide and below the stylesheet draws it as a sheet
92
- * from the bottom. The page must load `@onlyworlds/sdk/waymark.css`; no node carries a style attribute.
94
+ * visible when its menu closes), else the entry. Every Escape the fan-out handles stops there
95
+ * (`stopPropagation`), so a page's own Escape listener does not also run; an Escape while it is closed
96
+ * is the page's. A click outside closes it.
97
+ *
98
+ * Placement: below the name at its start, unless it would cross the box that clips it (the nearest
99
+ * ancestor of `target` whose overflow on that axis is not visible, within the window, else the window):
100
+ * measured at each open, it then opens at the name's end (class `ow-waymark__pop--end`) or above the
101
+ * name (`ow-waymark__pop--up`), where that side crosses less; the toast takes the same side. At 480 px
102
+ * wide and below (every portrait phone, and a desktop window as narrow) the stylesheet draws it as a
103
+ * sheet from the bottom, and no side is chosen. The page must load `@onlyworlds/sdk/waymark.css`; no
104
+ * node carries a style attribute.
93
105
  *
94
106
  * Refuses, before anything is drawn, an unknown option key by name and a value of the wrong kind (a
95
107
  * TypeError), and an address `elementAddress` refuses (an `OwAddressError`: a world id that is not an
package/dist/waymark.js CHANGED
@@ -45,8 +45,14 @@ var ENTRIES = ["mark", "menu", "both"];
45
45
  var SVG = "http://www.w3.org/2000/svg";
46
46
  var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
47
47
  var TOAST_MS = 2e3;
48
+ var GAP = 6;
49
+ var POP_END = "ow-waymark__pop--end";
50
+ var POP_UP = "ow-waymark__pop--up";
51
+ var TOAST_END = "ow-waymark__toast--end";
52
+ var TOAST_UP = "ow-waymark__toast--up";
48
53
  var COPIED = "Link copied";
49
54
  var NOT_COPIED = "Could not copy the link.";
55
+ var HERE = "You are here";
50
56
  var mounted = 0;
51
57
  var fail = (what) => {
52
58
  throw new TypeError(`mountWaymark: ${what}`);
@@ -223,8 +229,17 @@ function mountWaymark(target, options) {
223
229
  };
224
230
  const openWith = section("Open with");
225
231
  for (const r of rows) {
226
- const a = el("a", `ow-waymark__row${cannotOpen(r.state) ? " ow-waymark__row--cannot" : ""}`);
227
- a.href = r.href;
232
+ const cls = `ow-waymark__row${cannotOpen(r.state) ? " ow-waymark__row--cannot" : ""}`;
233
+ let a;
234
+ if (r.state === HERE) {
235
+ a = el("button", cls);
236
+ a.type = "button";
237
+ a.setAttribute("aria-current", "page");
238
+ a.dataset.here = "";
239
+ } else {
240
+ a = el("a", cls);
241
+ a.href = r.href;
242
+ }
228
243
  a.setAttribute("role", "menuitem");
229
244
  a.dataset.opener = r.id;
230
245
  a.appendChild(r.id === "onlyworlds" ? markSvg("ow-waymark__icon") : glyph(TOOL_GLYPH, "ow-waymark__icon"));
@@ -292,26 +307,64 @@ function mountWaymark(target, options) {
292
307
  let disposed = false;
293
308
  const items = () => Array.from(menu.querySelectorAll('[role="menuitem"], [role="menuitemradio"]')).filter((i) => !i.closest("[hidden]"));
294
309
  const isOpen = () => !pop.hidden;
310
+ const overflowOf = (cs, axis) => {
311
+ const [x, y = x] = (cs.overflow || "").trim().split(/\s+/);
312
+ return (axis === "x" ? cs.overflowX || x : cs.overflowY || y) || "visible";
313
+ };
314
+ const clipBox = (view, axis) => {
315
+ const edge = axis === "x" ? doc.documentElement.clientWidth || view.innerWidth : doc.documentElement.clientHeight || view.innerHeight;
316
+ for (let node = root.parentElement; node !== null && node !== doc.body && node !== doc.documentElement; node = node.parentElement) {
317
+ if (overflowOf(view.getComputedStyle(node), axis) === "visible") continue;
318
+ const r = node.getBoundingClientRect();
319
+ return axis === "x" ? [Math.max(0, r.left), Math.min(edge, r.right)] : [Math.max(0, r.top), Math.min(edge, r.bottom)];
320
+ }
321
+ return [0, edge];
322
+ };
323
+ const placePop = () => {
324
+ pop.classList.remove(POP_END, POP_UP);
325
+ let end = false;
326
+ let up = false;
327
+ if (win !== null && win.getComputedStyle(pop).position !== "fixed") {
328
+ const at = pop.getBoundingClientRect();
329
+ const anchor = root.getBoundingClientRect();
330
+ const [left, right] = clipBox(win, "x");
331
+ const [top, bottom] = clipBox(win, "y");
332
+ const pastRight = at.right - right;
333
+ end = pastRight > 0 && Math.max(0, left - (anchor.right - at.width)) < pastRight;
334
+ const pastBottom = at.bottom - bottom;
335
+ up = pastBottom > 0 && Math.max(0, top - (anchor.top - GAP - at.height)) < pastBottom;
336
+ }
337
+ pop.classList.toggle(POP_END, end);
338
+ pop.classList.toggle(POP_UP, up);
339
+ toast.classList.toggle(TOAST_END, end);
340
+ toast.classList.toggle(TOAST_UP, up);
341
+ };
295
342
  const open = (from, focus) => {
296
343
  if (isOpen()) return;
297
344
  openedBy = from;
298
345
  pressedInside = false;
299
346
  pop.hidden = false;
300
347
  scrim.hidden = false;
348
+ placePop();
301
349
  from.setAttribute("aria-expanded", "true");
302
350
  on(openListeners, doc, "pointerdown", onOutside, true);
303
351
  const list = items();
304
352
  (focus === "first" ? list[0] : list[list.length - 1])?.focus();
305
353
  };
306
354
  const failed = () => !addressLine.hidden;
355
+ const hideToast = () => {
356
+ toast.hidden = true;
357
+ toast.classList.remove(TOAST_END, TOAST_UP);
358
+ };
307
359
  const close = (refocus) => {
308
360
  if (!isOpen()) return;
309
361
  pop.hidden = true;
362
+ pop.classList.remove(POP_END, POP_UP);
310
363
  scrim.hidden = true;
311
364
  openedBy.setAttribute("aria-expanded", "false");
312
365
  offAll(openListeners);
313
366
  if (failed()) {
314
- toast.hidden = true;
367
+ hideToast();
315
368
  addressLine.hidden = true;
316
369
  toast.classList.remove("ow-waymark__toast--failed");
317
370
  }
@@ -323,7 +376,7 @@ function mountWaymark(target, options) {
323
376
  if (toastTimer !== null) timers.clearTimeout(toastTimer);
324
377
  toastTimer = timers.setTimeout(() => {
325
378
  toastTimer = null;
326
- toast.hidden = true;
379
+ hideToast();
327
380
  }, TOAST_MS);
328
381
  };
329
382
  const notCopied = (text) => {
@@ -354,12 +407,16 @@ function mountWaymark(target, options) {
354
407
  if (wasOpen) close(false);
355
408
  else open(e.currentTarget, "first");
356
409
  };
410
+ const owned = (e) => {
411
+ e.preventDefault();
412
+ e.stopPropagation();
413
+ };
357
414
  const onOpenerKey = (e) => {
358
415
  if (e.key === "ArrowDown" || e.key === "ArrowUp") {
359
416
  e.preventDefault();
360
417
  open(e.currentTarget, e.key === "ArrowDown" ? "first" : "last");
361
418
  } else if (e.key === "Escape" && isOpen()) {
362
- e.preventDefault();
419
+ owned(e);
363
420
  close(true);
364
421
  }
365
422
  };
@@ -373,7 +430,7 @@ function mountWaymark(target, options) {
373
430
  else if (e.key === "Home") next = list[0];
374
431
  else if (e.key === "End") next = list[list.length - 1];
375
432
  else if (e.key === "Escape") {
376
- e.preventDefault();
433
+ owned(e);
377
434
  close(true);
378
435
  return;
379
436
  } else if (e.key === " " && e.target.tagName === "A") {
@@ -412,6 +469,8 @@ function mountWaymark(target, options) {
412
469
  }
413
470
  );
414
471
  }
472
+ } else if (row.dataset.here !== void 0) {
473
+ close(true);
415
474
  } else {
416
475
  close(false);
417
476
  }
@@ -440,8 +499,8 @@ function mountWaymark(target, options) {
440
499
  }
441
500
  on(listeners, pop, "keydown", onMenuKey);
442
501
  on(listeners, toast, "keydown", ((e) => {
443
- if (e.key === "Escape") {
444
- e.preventDefault();
502
+ if (e.key === "Escape" && isOpen()) {
503
+ owned(e);
445
504
  close(true);
446
505
  }
447
506
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.116.1",
3
+ "version": "4.117.1",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {