@songsid/agend 2.3.0-beta.20 → 2.3.0-beta.22

package/dist/ui/fleet-route-scene.js

@@ -7,7 +7,10 @@
 //   the box's padding and the gutters between its rows and columns (L.pad, L.gap: wide enough for a few lines each)
 //   — are the only doors, so a line crosses a border at right angles, through a door, and never runs along it.
 // - Ends: pins on each card's sides (several on the long sides, one on the short), facing out; a line ends on a card,
-//   never on a box. A card with more lines than pins gets more, so two lines never start at one point.
+//   never on a box. A card with more lines than pins gets more, so two lines never start at one point. A short side
+//   facing a neighbour across less than ROUTE.SIDE (a column gutter, a phone's box padding) has no pin (#2329): a line
+//   into it would turn in that narrow gap with no room left for its arrowhead. libavoid turns a line into its pin right
+//   at the card's buffer, which leaves a head no straight run: lengthen() moves that turn out where there is room.
 // - Separation: libavoid nudges lines that share a run ROUTE.NUDGE apart; the same two ends and kind are one line (×N)
 //   before they get here (fleet-traffic.js).
 // A route that comes back otherwise (not orthogonal, not ending on its two shapes) is not drawn: that line keeps the
@@ -15,10 +18,13 @@
 import { OC } from "./fleet-canvas-layout.js";
 
 /** Buffer around every obstacle, the distance nudging keeps between lines, the cost of a bend, pins on a long side. */
-export const ROUTE = { BUF: 5, NUDGE: 8, SEG: 60, PINS: 4, MAX_PINS: 64, MAX_POINTS: 64, MAX_SHAPES: 600, MAX_CONNS: 120 };
+export const ROUTE = { BUF: 5, NUDGE: 8, SEG: 60, PINS: 4, MAX_PINS: 64, MAX_POINTS: 64, MAX_SHAPES: 600, MAX_CONNS: 120, SIDE: 30, RUN: 16 };
 /** libavoid's ConnDirFlags: the way a line leaves a pin. */
 const UP = 1, DOWN = 2, LEFT = 4, RIGHT = 8;
-const PINS_PER_CARD = ROUTE.PINS * 2 + 2;
+/** A shape's `sides`: which short sides have a pin (absent: both). */
+const SIDE_L = 1, SIDE_R = 2;
+const sidesOf = (sh) => sh.sides ?? SIDE_L | SIDE_R;
+const pinsOn = (sh) => ROUTE.PINS * 2 + ((sidesOf(sh) & SIDE_L) ? 1 : 0) + ((sidesOf(sh) & SIDE_R) ? 1 : 0);
 
 /** The shape a line's end is on: a card (General's or a member's) or a folded team's box. Null: not routed here. */
 function endShape(end) {
@@ -30,8 +36,9 @@ function endShape(end) {
 
 /**
  * The scene for layout `L` and the lines `lines` ([{ key, a, z }], a and z ends as fleet-traffic.js endOf gives them):
- * { shapes: [{ x, y, w, h, pins }], conns: [{ key, a, z }], boxes: [{ x, y, w, h }] } — `pins` 0 none (an obstacle
- * only), 1 the usual pins, more: that many on each long side (a busy card); every pin takes one line; `a`/`z` index
+ * { shapes: [{ x, y, w, h, pins, sides? }], conns: [{ key, a, z }], boxes: [{ x, y, w, h }] } — `pins` 0 none (an
+ * obstacle only), 1 the usual pins, more: that many on each long side (a busy card); `sides` the short sides with a pin
+ * (1 left, 2 right; absent: both); every pin takes one line; `a`/`z` index
  * shapes; `boxes` the open teams' outlines (separate() keeps lines off them). A line whose end is not a card or a folded box is left out (it keeps its lane).
  */
 export function routeScene(L, lines) {
@@ -57,9 +64,22 @@ export function routeScene(L, lines) {
     conns.push({ key: ln.key, a: ia, z: iz });
     for (const i of [ia, iz]) demand.set(i, (demand.get(i) || 0) + 1);
   }
+  // A short side with a pin only where a line has room to turn into it with its head: ROUTE.SIDE to the nearest shape
+  // beside it (a neighbour card, a box's wall piece).
+  for (const sh of shapes) {
+    if (!sh.pins) continue;
+    let left = Infinity, right = Infinity;
+    for (const o of shapes) {
+      if (o === sh || o.y >= sh.y + sh.h || o.y + o.h <= sh.y) continue;
+      if (o.x + o.w <= sh.x) left = Math.min(left, sh.x - o.x - o.w);
+      if (o.x >= sh.x + sh.w) right = Math.min(right, o.x - sh.x - sh.w);
+    }
+    const sides = (left >= ROUTE.SIDE ? SIDE_L : 0) | (right >= ROUTE.SIDE ? SIDE_R : 0);
+    if (sides !== (SIDE_L | SIDE_R)) sh.sides = sides;
+  }
   // A line each: a shape with more lines than pins gets more pins on its long sides (two lines never leave one point:
   // libavoid cannot nudge apart runs that start at the same point).
-  for (const [i, n] of demand) if (n > PINS_PER_CARD) shapes[i].pins = Math.min(ROUTE.MAX_PINS, Math.ceil((n - 2) / 2));
+  for (const [i, n] of demand) if (n > pinsOn(shapes[i])) shapes[i].pins = Math.min(ROUTE.MAX_PINS, Math.ceil((n - (pinsOn(shapes[i]) - ROUTE.PINS * 2)) / 2));
   return { shapes, conns, boxes };
 }
 
@@ -69,7 +89,8 @@ export function sceneOk(s) {
     || s.boxes.length > ROUTE.MAX_SHAPES) return null;
   const num = (v) => typeof v === "number" && Number.isFinite(v) && Math.abs(v) < 1e6;
   for (const b of s.boxes) if (!b || ![b.x, b.y, b.w, b.h].every(num) || b.w <= 0 || b.h <= 0) return null;
-  for (const sh of s.shapes) if (!sh || ![sh.x, sh.y, sh.w, sh.h].every(num) || sh.w <= 0 || sh.h <= 0 || !Number.isInteger(sh.pins) || sh.pins < 0 || sh.pins > ROUTE.MAX_PINS) return null;
+  for (const sh of s.shapes) if (!sh || ![sh.x, sh.y, sh.w, sh.h].every(num) || sh.w <= 0 || sh.h <= 0 || !Number.isInteger(sh.pins) || sh.pins < 0 || sh.pins > ROUTE.MAX_PINS
+    || (sh.sides !== undefined && (!Number.isInteger(sh.sides) || sh.sides < 0 || sh.sides > (SIDE_L | SIDE_R)))) return null;
   for (const c of s.conns) {
     if (!c || typeof c.key !== "string" || c.key.length > 2048) return null;
     for (const i of [c.a, c.z]) if (!Number.isInteger(i) || i < 0 || i >= s.shapes.length || !s.shapes[i].pins) return null;
@@ -97,15 +118,8 @@ export function answerRoute(A, m) {
   return { type: "routes", id: m.id, routes: scene ? [...routeWith(A, scene)] : null };
 }
 
-/**
- * libavoid nudges lines that share a run apart, but not always: in a channel shared by many lines it packs them closer
- * than ROUTE.NUDGE, and lines fanning out of one card can come back on the very same run. This pass moves the middle
- * segments of such lines (never a line's first or last, which end on a pin) sideways to the nearest place at least
- * SEPARATE from every parallel line along them — only where the moved segment and the two it joins stay clear of
- * every shape's buffer and keep their direction. What cannot move stays as libavoid left it.
- */
-export const SEPARATE = 6;
-export function separate(routes, scene) {
+/** What separate() and lengthen() share, on `scene` and the routes' points `pts` (which they move in place). */
+function mover(scene, pts) {
   const B = ROUTE.BUF - 0.5, OVER = 8;
   const segsOf = (r, p) => p.slice(1).map((q, i) => ({ r, i, h: p[i].y === q.y }));
   const coord = (p, s) => (s.h ? p[s.i].y : p[s.i].x);
@@ -120,9 +134,7 @@ export function separate(routes, scene) {
       && (scene.boxes ?? []).every((bx) => (h ? [bx.y, bx.y + bx.h].every((v) => Math.abs(v - y0) >= SEPARATE + 1) || Math.min(x1, bx.x + bx.w) - Math.max(x0, bx.x) <= 12
         : [bx.x, bx.x + bx.w].every((v) => Math.abs(v - x0) >= SEPARATE + 1) || Math.min(y1, bx.y + bx.h) - Math.max(y0, bx.y) <= 12));
   };
-  const keys = [...routes.keys()];
   const connOf = new Map(scene.conns.map((c) => [c.key, c]));
-  const pts = keys.map((k) => routes.get(k).map((p) => ({ x: p.x, y: p.y })));
   /** The segments of other lines (and this one's) parallel to segment s of line r, overlapping it, closer than SEPARATE. */
   const near = (r, s, c, lo, hi) => {
     const out = [];
@@ -131,8 +143,23 @@ export function separate(routes, scene) {
       const [l2, h2] = span(p, t);
       if (Math.min(hi, h2) - Math.max(lo, l2) > OVER) out.push(coord(p, t));
     }));
-    return out.filter((c2) => Math.abs(c2 - c) < SEPARATE);
+    return out.filter((c2) => Math.abs(c2 - c) < SEPARATE - 1e-6);              // libavoid's points carry float noise
   };
+  return { segsOf, coord, span, clear, near, connOf };
+}
+
+/**
+ * libavoid nudges lines that share a run apart, but not always: in a channel shared by many lines it packs them closer
+ * than ROUTE.NUDGE, and lines fanning out of one card can come back on the very same run. This pass moves the middle
+ * segments of such lines (never a line's first or last, which end on a pin) sideways to the nearest place at least
+ * SEPARATE from every parallel line along them — only where the moved segment and the two it joins stay clear of
+ * every shape's buffer and keep their direction. What cannot move stays as libavoid left it.
+ */
+export const SEPARATE = 6;
+export function separate(routes, scene) {
+  const keys = [...routes.keys()];
+  const pts = keys.map((k) => routes.get(k).map((p) => ({ x: p.x, y: p.y })));
+  const { segsOf, coord, span, clear, near, connOf } = mover(scene, pts);
   for (let pass = 0; pass < 8; pass++) {
     let moved = false;
     pts.forEach((p, r) => segsOf(r, p).forEach((s) => {
@@ -163,6 +190,43 @@ export function separate(routes, scene) {
   return new Map(keys.map((k, i) => [k, pts[i]]));
 }
 
+/**
+ * #2329: room for each line's arrowhead. libavoid turns a line into its last pin right at the card's buffer, so the
+ * last run (where the head goes) is a few px long. This pass moves the turn before it out from the card until the last
+ * run is ROUTE.RUN long (or up to 3 × SEPARATE more; where none fits, the longest that does): only where the moved segment and the two it joins stay clear of
+ * every shape's buffer, at least SEPARATE from every parallel line, and the run before the turn keeps its direction and
+ * 4 px. A line whose turn cannot move keeps its short run (fleet-traffic.js draws it with no head).
+ */
+export function lengthen(routes, scene) {
+  const keys = [...routes.keys()];
+  const pts = keys.map((k) => routes.get(k).map((p) => ({ x: p.x, y: p.y })));
+  const { coord, span, clear, near, connOf } = mover(scene, pts);
+  pts.forEach((p, r) => {
+    const n = p.length;
+    if (n < 4) return;                                                  // the turn's other end is the first pin
+    const z = p[n - 1], y = p[n - 2], x = p[n - 3], w = p[n - 4], h = y.y === z.y;
+    const at = (q) => (h ? q.x : q.y);
+    const u = Math.sign(at(y) - at(z));                                 // out from the card
+    if (!u || Math.abs(at(y) - at(z)) >= ROUTE.RUN) return;
+    const c0 = connOf.get(keys[r]);
+    const run = Math.abs(at(y) - at(z)), tries = [];
+    for (let t = ROUTE.RUN; t <= ROUTE.RUN + 3 * SEPARATE; t++) tries.push(t);
+    for (let t = ROUTE.RUN - 1; t > run; t--) tries.push(t);           // short of RUN (a phone's gutter): the longest that fits
+    for (const t of tries) {
+      const c2 = at(z) + u * t;
+      const a = h ? { x: c2, y: x.y } : { x: x.x, y: c2 }, b = h ? { x: c2, y: y.y } : { x: y.x, y: c2 };
+      if (Math.sign(at(a) - at(w)) !== Math.sign(at(x) - at(w)) || Math.abs(at(a) - at(w)) < 4) continue;
+      if (!clear(a, b) || !clear(w, a, n - 4 === 0 && c0 ? c0.a : -1) || !clear(b, z, c0 ? c0.z : -1)) continue;
+      const old = [p[n - 3], p[n - 2]];
+      p[n - 3] = a; p[n - 2] = b;
+      const ok = [n - 4, n - 3, n - 2].every((i) => { const s = { r, i, h: i === n - 3 ? !h : h }; const [lo, hi] = span(p, s); return !near(r, s, coord(p, s), lo, hi).length; });
+      if (ok) return;
+      [p[n - 3], p[n - 2]] = old;
+    }
+  });
+  return new Map(keys.map((k, i) => [k, pts[i]]));
+}
+
 /**
  * Route `scene` with libavoid instance `A` (libavoid-js 0.4.5's: its constants are numbers on `A`). A Map of
  * connection key → points, for the routes that pass routeOk only.
@@ -186,7 +250,8 @@ export function routeWith(A, scene) {
         const k = s.pins === 1 ? ROUTE.PINS : s.pins;
         const pin = (x, y, dir) => new A.ShapeConnectionPin(ref, 1, x, y, true, 0, dir).setExclusive(true);
         for (let i = 1; i <= k; i++) { pin(i / (k + 1), 0, UP); pin(i / (k + 1), 1, DOWN); }
-        pin(0, 0.5, LEFT); pin(1, 0.5, RIGHT);
+        if (sidesOf(s) & SIDE_L) pin(0, 0.5, LEFT);
+        if (sidesOf(s) & SIDE_R) pin(1, 0.5, RIGHT);
       }
       return ref;
     });
@@ -200,7 +265,7 @@ export function routeWith(A, scene) {
       const ok = routeOk(pts, scene, c);
       if (ok) out.set(c.key, ok);
     });
-    return ROUTE.SEPARATE === false ? out : separate(out, scene);
+    return ROUTE.SEPARATE === false ? out : lengthen(separate(out, scene), scene);
   } finally {
     A.destroy(r);
   }

package/dist/ui/fleet-traffic.js

@@ -178,8 +178,15 @@ function endOf(L, name) {
 
 // ── Routing: lanes the layout keeps empty ──
 
-/** A side lane's offset from the middle of the box's padding: at least 6 px from the box's border and from its cards. */
+/**
+ * A side lane's offset from the middle of the box's padding: at least 6 px from the box's border and from its cards.
+ * Negative: toward the border, on either side (#2329) — the first lines (o < 0) leave the cards a long last run for a head.
+ */
 const laneOffset = (o, PAD = OC.PAD) => Math.max(-PAD / 2 + 6, Math.min(PAD / 2 - 6, o * 0.5));
+const leftLaneOf = (b, io, PAD) => b.x + PAD / 2 + io;
+const rightLaneOf = (b, io, PAD) => b.x + b.w - PAD / 2 - io;
+/** Where a line meets a card's side, from the side's middle (#2329): its full offset, a head's width from its neighbours. */
+const sideOffset = (o) => Math.max(-OC.NH / 2 + 7, Math.min(OC.NH / 2 - 7, o));
 /** The layout's own box padding and gutter (a phone's are narrower). */
 const spacing = (L) => ({ PAD: L.pad ?? OC.PAD, GAP: L.gap ?? OC.GAP });
 
@@ -199,14 +206,14 @@ function outward(L, end, o) {
   const { NW, NH } = OC, { PAD, GAP } = spacing(L);
   const card = end.c, col = end.i % b.cols, rowI = Math.floor(end.i / b.cols), lines = Math.ceil(b.cells.length / b.cols);
   const io = laneOffset(o, PAD);
-  const leftLane = b.x + PAD / 2 + io, rightLane = b.x + b.w - PAD / 2 + io;
+  const leftLane = leftLaneOf(b, io, PAD), rightLane = rightLaneOf(b, io, PAD);
   let pts;
   if (col === 0 || col === b.cols - 1) {
-    const left = col === 0, lane = left ? leftLane : rightLane, cy = card.y + NH / 2 + io;
+    const left = col === 0, lane = left ? leftLane : rightLane, cy = card.y + NH / 2 + sideOffset(o);
     pts = [{ x: left ? card.x : card.x + NW, y: cy }, { x: lane, y: cy }, { x: lane, y: b.y }];
   } else {
     // A middle column: down into the gutter below its row, across to the nearer side lane.
-    const gy = card.y + NH + (rowI === lines - 1 ? PAD : GAP) / 2 + io / 2, cx = card.x + NW / 2 + o;
+    const gy = card.y + NH + (rowI === lines - 1 ? PAD : GAP) / 2 - io / 2, cx = card.x + NW / 2 + o;
     const lane = cx - b.x < b.w / 2 ? leftLane : rightLane;
     pts = [{ x: cx, y: card.y + NH }, { x: cx, y: gy }, { x: lane, y: gy }, { x: lane, y: b.y }];
   }
@@ -224,10 +231,10 @@ function toLane(L, end, lane, o) {
   const io = laneOffset(o, PAD);
   const left = lane < b.x + b.w / 2;
   if ((left && col === 0) || (!left && col === b.cols - 1)) {
-    const cy = card.y + NH / 2 + io;
+    const cy = card.y + NH / 2 + sideOffset(o);
     return [{ x: left ? card.x : card.x + NW, y: cy }, { x: lane, y: cy }];
   }
-  const gy = card.y + NH + (rowI === lines - 1 ? PAD : GAP) / 2 + io / 2, cx = card.x + NW / 2 + o;
+  const gy = card.y + NH + (rowI === lines - 1 ? PAD : GAP) / 2 - io / 2, cx = card.x + NW / 2 + o;
   return [{ x: cx, y: card.y + NH }, { x: cx, y: gy }, { x: lane, y: gy }];
 }
 /** Two cards in one open box: joined inside it, through the side lane nearer to them both (never out to the bus). */
@@ -235,7 +242,7 @@ function inBox(L, a, z, o) {
   const b = a.b, { PAD } = spacing(L);
   const io = laneOffset(o, PAD);
   const mid = ((a.i % b.cols) + (z.i % b.cols)) / 2;
-  const lane = mid <= (b.cols - 1) / 2 ? b.x + PAD / 2 + io : b.x + b.w - PAD / 2 + io;
+  const lane = mid <= (b.cols - 1) / 2 ? leftLaneOf(b, io, PAD) : rightLaneOf(b, io, PAD);
   return [...toLane(L, a, lane, o), ...toLane(L, z, lane, o).reverse()];
 }
 /** Two of General's cards: under them, through the gap above the first row (or the canvas's empty space below). */
@@ -280,6 +287,42 @@ export function badgeAt(pts) {
   return best;
 }
 
+// ── Arrowheads (#2329) ──
+
+/** A line's stroke width (px) by its kind and phase: the work's and its report's are heavier, a team pair's the most. */
+export const strokeOf = (hue, phase) => (phase === "work" || phase === "return" ? 3 : hue === "team" ? 3.5 : 2.5);
+/**
+ * The arrowhead and the ends. In stroke widths (the markers' units, fleet-canvas.js): a head LEN long and WIDE across,
+ * the line's own stroke ending BACK inside it (its round cap under the head, never out past the tip); the source dot
+ * DOT across. In px: the tip GAP short of the card, the dot's centre START off its card; a head only on a last straight
+ * run that holds it and ROOM of line before it — else the line ends GAP short with none (its dot and pulse show the way).
+ */
+export const HEAD = { LEN: 2.8, WIDE: 2.3, BACK: 1.4, DOT: 2, GAP: 3.5, START: 5, ROOM: 1 };
+/** Whether a line of stroke `w` px whose last straight run is `run` px long gets a head. */
+export const headFits = (run, w) => run >= HEAD.GAP + HEAD.LEN * w + HEAD.ROOM;
+/** An orthogonal polyline without repeated points or points in the middle of a straight run. */
+function corners(pts) {
+  const q = pts.filter((pt, i) => !i || pt.x !== pts[i - 1].x || pt.y !== pts[i - 1].y).map((pt) => ({ x: pt.x, y: pt.y }));
+  return q.filter((pt, i) => i === 0 || i === q.length - 1 || !((q[i - 1].x === pt.x && pt.x === q[i + 1].x) || (q[i - 1].y === pt.y && pt.y === q[i + 1].y)));
+}
+/** Route `pts` as drawn: its start moved `a` px along its first run, its end `b` px back along its last (each keeps 1 px). */
+export function trimEnds(pts, a, b) {
+  const q = corners(pts);
+  if (q.length < 2) return q;
+  const pull = (i, j, by) => {
+    const l = Math.hypot(q[j].x - q[i].x, q[j].y - q[i].y), t = Math.max(0, Math.min(by, l - 1)) / l;
+    q[i] = { x: q[i].x + (q[j].x - q[i].x) * t, y: q[i].y + (q[j].y - q[i].y) * t };
+  };
+  pull(0, 1, a);
+  pull(q.length - 1, q.length - 2, b);
+  return q;
+}
+/** The length of a route's last straight run. */
+export function lastRun(pts) {
+  const q = corners(pts);
+  return q.length < 2 ? 0 : Math.hypot(q[q.length - 1].x - q[q.length - 2].x, q[q.length - 1].y - q[q.length - 2].y);
+}
+
 // ── Edges ──
 
 /** The colour family of a kind: task, report, broadcast, and the rest (send, query, update). */
@@ -291,8 +334,10 @@ const settled = (phase) => (phase === "fading" || phase === "stale" ? "fading" :
 
 /**
  * The lines to draw from the store's items on layout `L`. `far`: zoomed out (one line per team pair). Each edge:
- * { key, hue, phase, n, from, to, d, pts, badge, a, z, routed } — `from`/`to` the instance (or team) names it joins, for
- * search; `a`/`z` its two ends (fleet-route-scene.js routes the ones on cards). `routed` (#2182): the router's points by
+ * { key, hue, phase, n, from, to, d, pts, w, head, badge, a, z, routed } — `from`/`to` the instance (or team) names it
+ * joins, for search; `pts` its route, end to end (on the cards); `d` the path drawn, its ends trimmed off the cards for
+ * the dot and the head (#2329); `w` its stroke width; `head` whether it has a head (headFits);
+ * `a`/`z` its two ends (fleet-route-scene.js routes the ones on cards). `routed` (#2182): the router's points by
  * line key (fleet-route.js); a line it has none for keeps its lane route — or, while a new answer is on its way, the
  * points the same two ends and kind had in the last one (a line changing phase keeps its place).
  */
@@ -339,7 +384,9 @@ export function trafficEdges(items, L, { far = false, max = MAX_EDGES, routed =
     const o = ((i % 7) - 3) * 7;                                                    // neighbours 7 px apart (within the ±22 px bus lane)
     const viaRouter = routedBy(key);
     const pts = viaRouter ?? route(L, g.a, g.z, o);
-    return { key, hue: g.hue, phase: g.phase, n: g.n, names: [...new Set(g.names)], d: pathOf(pts), pts, badge: g.n > 1 ? badgeAt(pts) : null,
+    const w = strokeOf(g.hue, g.phase), head = headFits(lastRun(pts), w);
+    const d = pathOf(trimEnds(pts, HEAD.START, HEAD.GAP + (head ? HEAD.BACK * w : 0)));
+    return { key, hue: g.hue, phase: g.phase, n: g.n, names: [...new Set(g.names)], d, pts, w, head, badge: g.n > 1 ? badgeAt(pts) : null,
       a: g.a, z: g.z, routed: !!viaRouter };
   });
 }

package/dist/ui/panel-settings.js

@@ -813,13 +813,13 @@ function WebSection({ ctx, staged }) {
     echo: web.echo_to_channel ?? true,
     log: web.log_tab === true,                                                  // #1218: off by default
     usagePub: web.usage_report_on_public_link === true,                         // #2122: off by default
-    pub: { allow_public: (web.public_link && web.public_link.allow_public) ?? true, ttl_minutes: (web.public_link && web.public_link.ttl_minutes) ?? 120, protocol: (web.public_link && web.public_link.protocol) ?? "http2" },
+    pub: { allow_public: (web.public_link && web.public_link.allow_public) ?? true, ttl_minutes: (web.public_link && web.public_link.ttl_minutes) ?? 120, protocol: (web.public_link && web.public_link.protocol) ?? "http2", hostname: (web.public_link && web.public_link.hostname) ?? "", tunnel_token_env: (web.public_link && web.public_link.tunnel_token_env) ?? "", origin_port: (web.public_link && web.public_link.origin_port) ?? 19282 },
     session: { absolute_hours: local.absolute_hours ?? null, idle_hours: local.idle_hours ?? null },
     terminal: { enabled: term.enabled ?? null, ttl_minutes: term.ttl_minutes ?? null },
   }), []);
   const text = (v) => (v === null || v === undefined ? "" : String(v));
   const [f, setF] = useState(() => ({
-    echo: original.echo, log: original.log, usagePub: original.usagePub, pub: original.pub.allow_public, ttl: String(original.pub.ttl_minutes), protocol: original.pub.protocol,
+    echo: original.echo, log: original.log, usagePub: original.usagePub, pub: original.pub.allow_public, ttl: String(original.pub.ttl_minutes), protocol: original.pub.protocol, hostname: original.pub.hostname, originPort: String(original.pub.origin_port),
     abs: text(original.session.absolute_hours), idle: text(original.session.idle_hours),
     termOn: original.terminal.enabled !== false, termTtl: text(original.terminal.ttl_minutes),
   }));
@@ -832,6 +832,8 @@ function WebSection({ ctx, staged }) {
   // the store and the validator apply it — so only an idle time that is typed can exceed the session length.
   const abs = value(f.abs) ?? 48, idle = value(f.idle) ?? Math.min(48, abs);
   const errors = {
+    hostname: f.hostname && !/^(?:https:\/\/)?[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)+\/?$/.test(f.hostname) ? "namedHostnameInvalid" : "",
+    originPort: !Number.isInteger(Number(f.originPort)) || Number(f.originPort) < 1024 || Number(f.originPort) > 65535 ? "namedPortInvalid" : "",
     ttl: !Number.isInteger(Number(f.ttl)) || Number(f.ttl) < 1 || Number(f.ttl) > 480 ? "publicTtl" : "",
     abs: hours(f.abs),
     idle: hours(f.idle) || (!hours(f.abs) && idle > abs ? "sessionIdleOver" : ""),
@@ -840,7 +842,7 @@ function WebSection({ ctx, staged }) {
   const ready = !overPublicLink && !Object.values(errors).some(Boolean);
   const review = () => {
     if (!ready) return;
-    const publicPatch = changedFields({ allow_public: f.pub, ttl_minutes: Number(f.ttl), protocol: f.protocol }, original.pub);
+    const publicPatch = changedFields({ allow_public: f.pub, ttl_minutes: Number(f.ttl), protocol: f.protocol, hostname: f.hostname, tunnel_token_env: f.hostname ? "AGEND_CLOUDFLARE_TUNNEL_TOKEN" : "", origin_port: Number(f.originPort) }, original.pub);
     const sessionPatch = changedFields({ absolute_hours: value(f.abs), idle_hours: value(f.idle) }, original.session);
     // The checkbox shows the default (on) for an unset key: only a real toggle is written; on again = back to the default.
     const terminalPatch = changedFields({ enabled: f.termOn === (original.terminal.enabled !== false) ? original.terminal.enabled : f.termOn ? null : false,
@@ -902,13 +904,18 @@ function WebSection({ ctx, staged }) {
       <p class="note">${tn("webUsagePublicHint")}</p>
       <label class="check"><input id="publicWebLink" type="checkbox" checked=${f.pub} onChange=${(e) => set("pub")(e.target.checked)} /><span>${tn("publicLink")}</span><${Impact} schema=${schema} field="web.public_link.allow_public" /></label>
       <p class="note">${tn("publicLinkHint")}</p>
+      <div class="grid2">
+        <div class="field"><label for="publicWebHostname">${tn("namedHostname")}</label><input id="publicWebHostname" type="text" value=${f.hostname} placeholder="agend.example.com" class=${errors.hostname ? "invalid" : ""} onInput=${(e) => set("hostname")(e.target.value)} /><${Feedback} error=${errors.hostname} /></div>
+        <div class="field"><label for="publicWebOriginPort">${tn("namedOriginPort")}</label><input id="publicWebOriginPort" type="number" min="1024" max="65535" value=${f.originPort} class=${errors.originPort ? "invalid" : ""} onInput=${(e) => set("originPort")(e.target.value)} /><${Feedback} error=${errors.originPort} /></div>
+      </div>
+      <p class="note">${tn("namedTunnelHint")} <a href="https://github.com/songsid/AgEnD/blob/main/docs/named-tunnel.md" target="_blank" rel="noopener noreferrer">${tn("namedTunnelSetup")}</a></p>
       <div class="grid2">
         <div class="field"><label for="publicWebTtl">${tn("publicTtl")}</label><input id="publicWebTtl" type="number" min="1" max="480" class=${errors.ttl ? "invalid" : ""} value=${f.ttl} onInput=${(e) => set("ttl")(e.target.value)} /><${Feedback} error=${errors.ttl} /></div>
         <div class="field"><label for="publicWebProtocol">${tn("publicProtocol")}</label><${Select} id="publicWebProtocol" value=${f.protocol} onChange=${set("protocol")} options=${["http2", "quic", "auto"]} /></div>
       </div>
     </section>
     </fieldset>
-    ${overPublicLink ? null : html`<${GuestsCard} ctx=${ctx} staged=${staged} /><${WebAuthorityCard} ctx=${ctx} staged=${staged} />`}
+    ${overPublicLink ? null : html`<${PublicTunnelToken} /><${GuestsCard} ctx=${ctx} staged=${staged} /><${WebAuthorityCard} ctx=${ctx} staged=${staged} />`}
     <section class="card s-web-readonly"><h3>${tn("webReadOnlyTitle")}</h3>
       <p class="note">${tn("webReadOnlyLead")}</p>
       <dl class="s-web-ro">${WEB_READ_ONLY.map((k) => html`<div key=${k}><dt><code>${k}</code></dt><dd>${shown(k)}</dd></div>`)}</dl>
@@ -1033,3 +1040,49 @@ function HelpDialog({ onClose }) {
 }
 
 export { worstImpact, ACCESS_MODES };
+
+function PublicTunnelToken() {
+  const lease = useLease("public-tunnel-token");
+  const [secret, setSecret] = useState("");
+  const [present, setPresent] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const inFlight = useRef(false);
+  const [message, setMessage] = useState("");
+  const base = "/api/settings/public-tunnel-token";
+  const refresh = async () => {
+    const result = await api(base);
+    if (lease.current() && result.ok) setPresent(result.body?.[0]?.token_present === true);
+  };
+  useEffect(() => { refresh().catch(() => {}); }, []);
+  const go = async (clear) => {
+    if (inFlight.current || !clear && !secret) return;
+    const value = secret;
+    setSecret(""); inFlight.current = true; setBusy(true); setMessage("");
+    const key = newKey("tunnel-token");
+    try {
+      const prepared = await api(`${base}/verify`, { method: "POST", headers: { "Idempotency-Key": key }, body: JSON.stringify(clear ? { clear: true } : { secret: value }) });
+      if (!lease.current()) return;
+      if (!prepared.ok) throw Error("refused");
+      const applied = await confirmedWrite(`${base}/apply`, { method: "POST", key, label: tn(clear ? "namedTokenClear" : "namedTokenSet"), body: { verification_id: prepared.body?.verification_id, idempotency_key: key } });
+      let body = applied.body || {};
+      for (let n = 0; applied.ok && body.job_id && body.result === "applying" && n < 60; n++) {
+        await new Promise(r => setTimeout(r, 250));
+        const status = await api(`${base}/apply/${encodeURIComponent(body.job_id)}`);
+        if (status.ok) body = status.body || body;
+      }
+      if (lease.current()) {
+        setMessage(tn(applied.ok && body.result === "reloaded" ? "namedTokenSaved" : body.result === "pending_confirmation" ? "awaitingConfirmation" : "applyFailed"));
+        await refresh();
+      }
+    } catch { if (lease.current()) setMessage(tn("applyFailed")); }
+    finally { inFlight.current = false; if (lease.current()) setBusy(false); }
+  };
+  return html`<section class="card"><h3>${tn("namedToken")}</h3>
+    <p class="note">${tn("namedTokenHint")}</p>
+    <span class="tag">${present ? tn("keyConfigured") : tn("keyNotConfigured")}</span>
+    <input id="publicTunnelToken" type="password" autocomplete="new-password" aria-label=${tn("namedToken")} value=${secret} onInput=${e => setSecret(e.target.value)} />
+    <button type="button" class="btn btn-sm" disabled=${busy || !secret} onClick=${() => go(false)}>${tn("namedTokenSet")}</button>
+    <button type="button" class="btn btn-sm" disabled=${busy || !present} onClick=${() => go(true)}>${tn("namedTokenClear")}</button>
+    ${message ? html`<p class="note" role="status">${message}</p>` : null}
+  </section>`;
+}

package/dist/ui/settings-appearance.js

@@ -45,7 +45,7 @@ export function AppearanceSection() {
   const publicLink = typeof document !== "undefined" && document.body && document.body.dataset.publicLink === "1";
   if (publicLink) return html`<section class="card s-appearance"><h3>${tn("cssTitle")}</h3><p class="sub">${tn("cssPublicLink")}</p></section>`;
   const group = (key) => html`<h2 class="s-ap-group">${tn(key)}</h2>`;
-  return html`${group("groupLook")}<${ThemesCard} /><${IdentityColorCard} /><${CardSizeCard} />
+  return html`${group("groupLook")}<${ThemesCard} /><${IdentityColorCard} /><${CardSizeCard} /><${AppIconCard} />
     ${group("groupLayout")}<${SidebarWidgetCard} />
     ${group("groupCss")}<${OwnerCssCard} /><${DeviceCard} />
     ${group("groupMods")}<${ModsCard} /><${EffectsCard} />
@@ -127,6 +127,131 @@ function CardSizeCard() {
   </section>`;
 }
 
+/**
+ * #2308: the image as one square PNG the host makes the icon sizes from — centre-cropped, drawn at 512 px if smaller
+ * (marked low-resolution), as it is up to 1024 px, else 1024. The browser decodes whatever it can show (PNG, JPG, WebP);
+ * the host takes only that PNG.
+ */
+export async function appIconPng(file) {
+  const bmp = await createImageBitmap(file);
+  try {
+    const side = Math.min(bmp.width, bmp.height);
+    const out = Math.min(1024, Math.max(512, side));
+    const canvas = document.createElement("canvas");
+    canvas.width = canvas.height = out;
+    const g = canvas.getContext("2d");
+    g.imageSmoothingQuality = "high";
+    g.drawImage(bmp, (bmp.width - side) / 2, (bmp.height - side) / 2, side, side, 0, 0, out, out);
+    const blob = await new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+    if (!blob) throw new Error("no PNG");
+    return { blob, low: side < 512 };
+  } finally {
+    if (bmp.close) bmp.close();
+  }
+}
+
+/** #2308: this page's icon links follow a change at once (the next pages carry the version from the host). */
+export function refreshAppIconLinks(version, custom) {
+  if (typeof document === "undefined") return;
+  const v = encodeURIComponent(version);
+  const head = document.head;
+  const links = [...head.querySelectorAll("link")];
+  const byPath = (path) => links.find((l) => (l.getAttribute("href") || "").split("?")[0] === path);
+  for (const [path, rel] of [["/favicon.ico", "icon"], ["/apple-touch-icon.png", "apple-touch-icon"], ["/manifest.webmanifest", "manifest"]]) {
+    const el = byPath(path);
+    if (el && el.getAttribute("rel") === rel) el.setAttribute("href", `${path}?v=${v}`);
+  }
+  const svg = byPath("/favicon.svg");
+  if (custom && svg) svg.remove();
+  else if (!custom && !svg) {
+    const link = document.createElement("link");
+    for (const [k, val] of [["rel", "icon"], ["href", `/favicon.svg?v=${v}`], ["type", "image/svg+xml"], ["sizes", "any"]]) link.setAttribute(k, val);
+    head.appendChild(link);
+  }
+}
+
+/**
+ * #2308: the app icon — what a browser tab and a home screen show. One picture for every page (sign-in and the public
+ * link too); an admin changes it, everyone else sees it.
+ */
+function AppIconCard() {
+  const [state, setState] = useState(null);
+  const [canWrite, setCanWrite] = useState(false);
+  const [picked, setPicked] = useState(null);           // { blob, url, low }
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const file = useRef(null);
+  const load = async () => {
+    const r = await call("/ui/app-icon");
+    setState(r.ok && r.body && typeof r.body.version === "string" ? r.body : { failed: true });
+  };
+  useEffect(() => {
+    load();
+    const auth = typeof window !== "undefined" ? window.AgendAuth : null;
+    if (auth && auth.canWrite) Promise.resolve(auth.canWrite()).then((v) => setCanWrite(v === true), () => {});
+  }, []);
+  useEffect(() => () => { if (picked) URL.revokeObjectURL(picked.url); }, [picked]);
+  const title = html`<${CardTitle} title=${tn("appIconTitle")} topic="app-icon" />`;
+  if (!state) return html`<section class="card s-appearance s-app-icon">${title}<p class="sub">…</p></section>`;
+  if (state.failed) return html`<section class="card s-appearance s-app-icon">${title}<p class="err">${tn("appIconLoadFailed")}</p></section>`;
+
+  const choose = async () => {
+    const f = file.current && file.current.files && file.current.files[0];
+    if (file.current) file.current.value = "";
+    if (!f) return;
+    setError("");
+    try {
+      const made = await appIconPng(f);
+      setPicked({ ...made, url: URL.createObjectURL(made.blob) });
+    } catch {
+      setError(tn("appIconNotAnImage"));
+    }
+  };
+  const answered = (r, done) => {
+    setBusy(false);
+    if (!r.ok) {
+      const known = ["app_icon_too_large", "app_icon_not_png", "app_icon_unreadable", "app_icon_admin_only", "app_icon_needs_a_signed_in_person", "app_icon_busy", "app_icon_superseded", "app_icon_not_reset"];
+      setError(known.includes(r.body && r.body.error) ? tn(`appIconError_${r.body.error}`, (r.body && r.body.detail) || "") : tn("appIconError_other", (r.body && r.body.error) || String(r.status)));
+      return;
+    }
+    setState(r.body);
+    setPicked(null);
+    refreshAppIconLinks(r.body.version, r.body.custom);
+    toast(done);
+  };
+  const use = async () => {
+    setBusy(true); setError("");
+    answered(await call("/ui/app-icon", { method: "PUT", headers: { "Content-Type": "image/png" }, body: picked.blob }), tn("appIconSaved"));
+  };
+  const reset = async () => {
+    setBusy(true); setError("");
+    answered(await call("/ui/app-icon", { method: "DELETE" }), tn("appIconResetDone"));
+  };
+  const v = encodeURIComponent(state.version);
+  return html`<section class="card s-appearance s-app-icon">${title}
+    <p class="sub">${tn("appIconLead")}</p>
+    <div class="s-app-icon-row">
+      <figure class="s-app-icon-now"><img class="s-app-icon-big" src=${`/apple-touch-icon.png?v=${v}`} width="96" height="96" alt=${tn("appIconCurrent")} />
+        <img class="s-app-icon-small" src=${`/icon-192.png?v=${v}`} width="32" height="32" alt="" />
+        <figcaption>${state.custom ? tn("appIconCustom") : tn("appIconDefault")}</figcaption></figure>
+      ${picked ? html`<figure class="s-app-icon-new"><img class="s-app-icon-big" src=${picked.url} width="96" height="96" alt=${tn("appIconPreview")} />
+        <figcaption>${tn("appIconPreview")}</figcaption></figure>` : null}
+    </div>
+    ${picked && picked.low ? html`<p class="sub s-app-icon-low">${tn("appIconLow")}</p>` : null}
+    ${error ? html`<p class="err" role="alert">${error}</p>` : null}
+    ${canWrite ? html`<div class="s-css-actions">
+      <input ref=${file} type="file" class="sr-only" id="s-app-icon-file" accept="image/png,image/jpeg,image/webp" onChange=${choose} />
+      ${picked ? html`
+        <button type="button" class="btn btn-primary" disabled=${busy} onClick=${use}><${Icon} name="check" size=${16} />${tn("appIconUse")}</button>
+        <button type="button" class="btn" disabled=${busy} onClick=${() => setPicked(null)}>${tn("appIconCancel")}</button>`
+      : html`<button type="button" class="btn" disabled=${busy} onClick=${() => file.current && file.current.click()}>${tn("appIconChoose")}</button>`}
+      ${state.custom && !picked ? html`<button type="button" class="btn" disabled=${busy} onClick=${reset}>${tn("appIconReset")}</button>` : null}
+    </div>` : html`<p class="sub">${tn("appIconReadOnly")}</p>`}
+    <p class="sub">${tn("appIconWho")}</p>
+    <p class="sub">${tn("appIconIos")}</p>
+  </section>`;
+}
+
 const LIMIT_FIELDS = [["portrait", "max_width"], ["portrait", "max_height"], ["portrait", "max_kib"], ["banner", "max_width"], ["banner", "max_height"], ["banner", "max_kib"],
   ["instance_quota", "files"], ["instance_quota", "mib"]];
 /**

package/dist/ui/settings-learn.js

@@ -13,6 +13,7 @@ export const LEARN_ANCHORS = {
   colors: ["identity-colours", "識別色"], css: ["custom-css-settings--web-appearance", "自訂-css設定--網頁外觀"], themes: ["agents-themes", "agent-的主題"],
   cards: ["identity-cards", "身分卡"], limits: ["card-upload-limits", "身分卡上傳限制"], widgets: ["widgets", "小工具"], mods: ["mods", "mod"],
   effects: ["effects", "效果"], restore: ["restore-defaults", "還原預設值"],
+  "app-icon": ["app-icon", "app-圖示"],
 };
 export function learnHref(topic, language = lang()) {
   const zh = language === "zh-TW";