@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 +1 -1
- package/CHANGELOG.md +15 -0
- package/README.md +2 -2
- package/SCHEMA.md +1 -1
- package/dist/waymark.css +24 -2
- package/dist/waymark.d.ts +14 -2
- package/dist/waymark.js +67 -8
- package/package.json +1 -1
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.
|
|
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
|
|
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.
|
|
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
|
-
/*
|
|
312
|
-
|
|
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.
|
|
92
|
-
*
|
|
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
|
|
227
|
-
a
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
502
|
+
if (e.key === "Escape" && isOpen()) {
|
|
503
|
+
owned(e);
|
|
445
504
|
close(true);
|
|
446
505
|
}
|
|
447
506
|
}));
|