@vibefield/rosetta-room 0.0.0-stage → 0.1.1

package/dist/lib/transcript/favicons.d.ts

@@ -0,0 +1,54 @@
+import type { KeyValueStore } from "../room-storage.js";
+/** What a site wears while nothing is known, and what it wears when the
+ * answer was no. `off` is the setting; `globe` is the outcome. */
+export type FaviconState = "off" | "loading" | "ready" | "globe";
+export interface FaviconResult {
+    /** A `data:` URL, or null in every state but `ready`. */
+    readonly src: string | null;
+    readonly state: FaviconState;
+}
+/** One room's icons: the setting, and one shared per-site map so eight lines
+ * from one site produce one ask. */
+export interface FaviconStore {
+    /** Whether this room may ask its host for site icons. */
+    enabled(): boolean;
+    /** Turn site icons on or off. Turning them OFF forgets what was already
+     * fetched, so the room stops showing icons it is no longer allowed to ask
+     * for — a setting that only applied to future sites would be a half-truth. */
+    setEnabled(on: boolean): void;
+    subscribe(listener: () => void): () => void;
+    /** Advances whenever the setting changes. */
+    generation(): number;
+    ask(host: string): void;
+    snapshot(host: string | null): FaviconResult;
+}
+/**
+ * The store over a host's `favicon` act, or over none: a plain browser tab
+ * has no host to ask, which is the globe, permanently, and stated rather than
+ * retried.
+ */
+export declare function createFaviconStore(fetchIcon: ((host: string) => Promise<string | null>) | null, store: KeyValueStore | null): FaviconStore;
+/** The host a source url belongs to, or null when it names none. Lowercased,
+ * because a host is case-insensitive and the cache is not. */
+export declare function hostOf(url: string): string | null;
+/** The setting, live. A toggle binds to this; so does every icon in the
+ * room, which is how turning it off empties them in the same frame. */
+export declare function useSiteIconsEnabled(): boolean;
+/** Turn the room's site icons on or off. */
+export declare function useSetSiteIconsEnabled(): (on: boolean) => void;
+/**
+ * One host's icon.
+ *
+ * Returns `off` when the setting is off, `loading` while the host is being
+ * asked, `ready` with a `data:` URL when there is one, and `globe` for every
+ * no — a host with no icon, a refusal, a 404, a browser tab with no host.
+ * A null host is a globe too, which is what a source with no parseable url
+ * honestly is.
+ *
+ * The ask happens during the subscribe, not in an effect: several lines
+ * naming one site share the room's entry, so the request is made once
+ * regardless of how many of them mount. The setting's generation also keys
+ * the subscription: even an off/on pair batched into one render must start
+ * a fresh request, since turning off invalidates the previous one.
+ */
+export declare function useFavicon(host: string | null): FaviconResult;

package/dist/lib/transcript/favicons.js

@@ -0,0 +1,183 @@
+// Site icons, as the renderer sees them.
+//
+// A search's sources are the one place in this room where identity should
+// carry colour: a site's own icon is content, and it is the fastest way to
+// tell GitHub from MDN from somebody's blog. The icon is not in the protocol
+// — a source carries a url and a title and nothing else — so it has to be
+// fetched, and fetching is a network act the renderer is not allowed to
+// perform. It asks the room's host (`HostPort.favicon`), which validates the
+// host, dials the SITE rather than a favicon service, and caches per host.
+//
+// Because it IS a network act, it is named and it is optional: `fetch site
+// icons`, on by default, off in one call. Off means off — no request is made,
+// and every site wears the globe.
+//
+// This module holds the room's half: one store per room (the setting and one
+// shared per-host map, so eight lines from one site produce one ask), and the
+// hooks the components read. It deliberately holds no component and no markup.
+import { useCallback, useSyncExternalStore } from "react";
+import { useRoom } from "../../room-context.js";
+import { webAddress } from "./web-address.js";
+/** Versioned like `tintSeq.v1`, and stored the same way, under the room's
+ * storage prefix: a renderer preference with no home on the daemon side yet. */
+const STORE_KEY = "siteIcons.v1";
+const OFF = { src: null, state: "off" };
+const LOADING = { src: null, state: "loading" };
+const GLOBE = { src: null, state: "globe" };
+/**
+ * The store over a host's `favicon` act, or over none: a plain browser tab
+ * has no host to ask, which is the globe, permanently, and stated rather than
+ * retried.
+ */
+export function createFaviconStore(fetchIcon, store) {
+    let enabled = null;
+    /** Settled answers, by host: a `data:` URL, or null for every honest no.
+     * The shell caches across launches; this caches across components, so a
+     * ledger of forty web lines makes one ask per site and not one per line. */
+    const known = new Map();
+    /** One stable `ready` value per host. `useSyncExternalStore` compares
+     * snapshots by identity, so a fresh object per read would render forever. */
+    const results = new Map();
+    /** Hosts currently being asked about. */
+    const pending = new Map();
+    let generation = 0;
+    /** Every mounted `useFavicon`, so a settled answer redraws the lines waiting
+     * on it and a changed setting redraws all of them. */
+    const listeners = new Set();
+    const announce = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    function isEnabled() {
+        if (enabled === null) {
+            try {
+                // Anything but an explicit "off" is on, so a blocked or corrupt store
+                // lands on the default rather than silently disabling the feature.
+                enabled = store?.getItem(STORE_KEY) !== "off";
+            }
+            catch {
+                enabled = true;
+            }
+        }
+        return enabled;
+    }
+    function resultFor(host, src) {
+        const existing = results.get(host);
+        if (existing !== undefined && existing.src === src)
+            return existing;
+        const made = { src, state: "ready" };
+        results.set(host, made);
+        return made;
+    }
+    return {
+        enabled: isEnabled,
+        setEnabled(on) {
+            if (isEnabled() === on)
+                return;
+            enabled = on;
+            generation += 1;
+            try {
+                store?.setItem(STORE_KEY, on ? "on" : "off");
+            }
+            catch {
+                // storage refused; the choice holds for this run
+            }
+            if (!on) {
+                known.clear();
+                results.clear();
+                pending.clear();
+            }
+            announce();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        generation: () => generation,
+        ask(host) {
+            if (known.has(host) || pending.has(host))
+                return;
+            if (fetchIcon === null) {
+                known.set(host, null);
+                return;
+            }
+            const requestGeneration = generation;
+            pending.set(host, requestGeneration);
+            fetchIcon(host)
+                .then((src) => {
+                if (generation !== requestGeneration)
+                    return;
+                known.set(host, typeof src === "string" && src !== "" ? src : null);
+            })
+                .catch(() => {
+                if (generation !== requestGeneration)
+                    return;
+                // The host refused or went away. Same fact to a reader: the globe.
+                known.set(host, null);
+            })
+                .finally(() => {
+                if (pending.get(host) === requestGeneration) {
+                    pending.delete(host);
+                    announce();
+                }
+            });
+        },
+        snapshot(host) {
+            if (!isEnabled())
+                return OFF;
+            if (host === null)
+                return GLOBE;
+            const src = known.get(host);
+            if (src === undefined)
+                return LOADING;
+            // Frozen results, not fresh objects: `useSyncExternalStore` compares by
+            // identity and a new object every read is an infinite render.
+            return src === null ? GLOBE : resultFor(host, src);
+        },
+    };
+}
+/** The host a source url belongs to, or null when it names none. Lowercased,
+ * because a host is case-insensitive and the cache is not. */
+export function hostOf(url) {
+    return webAddress(url)?.host ?? null;
+}
+// ── the hooks ─────────────────────────────────────────────────────────────
+/** The setting, live. A toggle binds to this; so does every icon in the
+ * room, which is how turning it off empties them in the same frame. */
+export function useSiteIconsEnabled() {
+    const { favicons } = useRoom();
+    return useSyncExternalStore(favicons.subscribe, favicons.enabled, favicons.enabled);
+}
+/** Turn the room's site icons on or off. */
+export function useSetSiteIconsEnabled() {
+    return useRoom().favicons.setEnabled;
+}
+/**
+ * One host's icon.
+ *
+ * Returns `off` when the setting is off, `loading` while the host is being
+ * asked, `ready` with a `data:` URL when there is one, and `globe` for every
+ * no — a host with no icon, a refusal, a 404, a browser tab with no host.
+ * A null host is a globe too, which is what a source with no parseable url
+ * honestly is.
+ *
+ * The ask happens during the subscribe, not in an effect: several lines
+ * naming one site share the room's entry, so the request is made once
+ * regardless of how many of them mount. The setting's generation also keys
+ * the subscription: even an off/on pair batched into one render must start
+ * a fresh request, since turning off invalidates the previous one.
+ */
+export function useFavicon(host) {
+    const { favicons } = useRoom();
+    const revision = useSyncExternalStore(favicons.subscribe, favicons.generation, favicons.generation);
+    const on = favicons.enabled();
+    const subscribeToHost = useCallback((listener) => {
+        if (host !== null && on)
+            favicons.ask(host);
+        return favicons.subscribe(listener);
+    }, [favicons, host, on, revision]);
+    const snapshot = useCallback(() => favicons.snapshot(host), [favicons, host, on]);
+    return useSyncExternalStore(subscribeToHost, snapshot, snapshot);
+}

package/dist/lib/transcript/head-of-document.d.ts

@@ -0,0 +1,27 @@
+import type { TimelineFeed } from "../hooks.js";
+export interface HeadOfDocumentOptions {
+    /** Upward travel that spends the bar. Default 120px. */
+    readonly threshold?: number;
+    /** Stillness that decays the accumulator. Default 500ms. */
+    readonly decayMs?: number;
+    /** The scroll depth `--frost` reaches 1 at. Default 24px. */
+    readonly frostRange?: number;
+    /** How long the receipt pill stands. Default 1800ms, the record's clock. */
+    readonly receiptMs?: number;
+    /** Set false to leave the listeners unbound (a search view, an empty room). */
+    readonly enabled?: boolean;
+}
+export interface HeadOfDocument {
+    /** The accumulator as the bar reads it, 0..1. */
+    readonly pull: number;
+    /** `--frost`, 0..1 — also written onto the scroller for the CSS to consume. */
+    readonly frost: number;
+    /** The last landing while its receipt stands, then null. */
+    readonly receipt: {
+        readonly count: number;
+        readonly seq: number;
+    } | null;
+}
+export declare function useHeadOfDocument(scrollerRef: {
+    current: HTMLElement | null;
+}, feed: TimelineFeed, options?: HeadOfDocumentOptions): HeadOfDocument;

package/dist/lib/transcript/head-of-document.js

@@ -0,0 +1,274 @@
+// §08 — the head of the document, wired to a scroller.
+//
+// Four jobs, all of them listeners over `head-state.ts`'s arithmetic:
+//   approach — within one viewport of the top, fetch the page above and HOLD it
+//   the pull  — 120px of upward travel at scrollTop 0 spends the bar
+//   landing   — the page lands above the viewport, which does not move
+//   the fade  — `--frost` rises 0 → 1 over the first 24px of scroll
+//
+// CONTRACT WITH THE ROW COMPONENTS: every top-level row/turn element inside the
+// scroller carries `data-timeline-id="<timeline_id>"`. Landing finds the first
+// old row by that attribute, measures it before and after the prepend, and adds
+// the difference to scrollTop — Chromium suppresses scroll anchoring at scroll
+// position zero, which is precisely where this fires. Without the attribute the
+// hook falls back to a scrollHeight delta, which is correct but coarser.
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { advancePull, frostOf, FROST_RANGE_PX, initialPull, PULL_DECAY_MS, PULL_THRESHOLD_PX, pullProgress, RECEIPT_MS, } from "./head-state.js";
+/** A box the reader can see. A line folded away inside a closed run, or an
+ *  element not laid out, measures 0×0 at the viewport's origin — anchoring on
+ *  it would hold nothing still and land the reader at the top instead. */
+function visibleBox(element) {
+    const box = element.getBoundingClientRect();
+    if (box.height > 0 || box.width > 0)
+        return box;
+    // A closed activity run is still the visible location of its events. After
+    // an earlier page joins it, anchor to that same run instead of the next chat.
+    const group = element.closest(".tr-activity__list[hidden]")?.parentElement;
+    if (group !== null && group !== undefined) {
+        const groupBox = group.getBoundingClientRect();
+        if (groupBox.height > 0)
+            return groupBox;
+    }
+    return null;
+}
+/** Where the row with this id is drawn now, skipping any hidden twin: one
+ *  timeline id may be stamped on a turn wrapper AND on the line inside it, and
+ *  after a prepend the turns re-split, so the first match in DOM order can be
+ *  the folded one. */
+function rowTop(scroller, id) {
+    const twins = scroller.querySelectorAll(`[data-timeline-id="${CSS.escape(id)}"]`);
+    for (const twin of twins) {
+        const box = visibleBox(twin);
+        if (box !== null)
+            return box.top;
+    }
+    return null;
+}
+function measureAnchor(scroller) {
+    const edge = scroller.getBoundingClientRect().top;
+    let id = null;
+    let top = 0;
+    // The first VISIBLE row whose bottom has not scrolled past the top edge:
+    // that is the one under the reader's eye, whatever the DOM order says.
+    for (const row of scroller.querySelectorAll("[data-timeline-id]")) {
+        const box = visibleBox(row);
+        if (box === null || box.bottom < edge)
+            continue;
+        id = row.dataset.timelineId ?? null;
+        top = box.top;
+        break;
+    }
+    return { id, top, scrollHeight: scroller.scrollHeight };
+}
+export function useHeadOfDocument(scrollerRef, feed, options = {}) {
+    const threshold = options.threshold ?? PULL_THRESHOLD_PX;
+    const decayMs = options.decayMs ?? PULL_DECAY_MS;
+    const frostRange = options.frostRange ?? FROST_RANGE_PX;
+    const receiptMs = options.receiptMs ?? RECEIPT_MS;
+    const enabled = options.enabled ?? true;
+    const [pull, setPull] = useState(0);
+    const [frost, setFrost] = useState(0);
+    const [receipt, setReceipt] = useState(null);
+    const pullRef = useRef(initialPull);
+    const anchorRef = useRef(null);
+    const frameRef = useRef(null);
+    const decayRef = useRef(null);
+    // The listeners fire between commits; they must never close over a stale
+    // feed. One ref, refreshed every render, is the whole trick.
+    const feedRef = useRef(feed);
+    feedRef.current = feed;
+    const setPullModel = useCallback((next) => {
+        pullRef.current = next;
+        setPull(pullProgress(next, threshold));
+    }, [threshold]);
+    // ── the landing ───────────────────────────────────────────────────────────
+    // Declared FIRST so it reads the anchor cached by the commit BEFORE the
+    // prepend; the refresher below then overwrites it for the next landing.
+    const landSeq = feed.landed?.seq ?? null;
+    useLayoutEffect(() => {
+        if (landSeq === null)
+            return;
+        const scroller = scrollerRef.current;
+        const before = anchorRef.current;
+        if (scroller === null || before === null)
+            return;
+        const top = before.id === null ? null : rowTop(scroller, before.id);
+        // The row that was under the reader's eye stays exactly where it was.
+        // Chromium suppresses scroll anchoring at scroll position zero — precisely
+        // where this fires — so the prepend adds the difference itself.
+        const delta = top !== null ? top - before.top : scroller.scrollHeight - before.scrollHeight;
+        if (delta !== 0)
+            scroller.scrollTop += delta;
+        anchorRef.current = measureAnchor(scroller);
+    }, [landSeq, scrollerRef]);
+    // Keep the anchor fresh: every commit, and every scroll frame below.
+    useLayoutEffect(() => {
+        const scroller = scrollerRef.current;
+        if (scroller !== null)
+            anchorRef.current = measureAnchor(scroller);
+    });
+    // ── the receipt ───────────────────────────────────────────────────────────
+    const landed = feed.landed;
+    useEffect(() => {
+        if (landed === null || landed.count <= 0) {
+            // A session change drops the landing; a stale receipt must go with it.
+            setReceipt(null);
+            return;
+        }
+        setReceipt({ count: landed.count, seq: landed.seq });
+        const timer = window.setTimeout(() => setReceipt(null), receiptMs);
+        return () => window.clearTimeout(timer);
+    }, [landed, receiptMs]);
+    // ── the listeners ─────────────────────────────────────────────────────────
+    useEffect(() => {
+        const scroller = scrollerRef.current;
+        if (scroller === null || !enabled)
+            return;
+        const clearDecay = () => {
+            if (decayRef.current !== null)
+                window.clearTimeout(decayRef.current);
+            decayRef.current = null;
+        };
+        const armDecay = () => {
+            clearDecay();
+            decayRef.current = window.setTimeout(() => {
+                decayRef.current = null;
+                setPullModel(initialPull);
+            }, decayMs);
+        };
+        /** The bar is spent. A held page lands now; a fetch in flight lands on
+         *  arrival; and a pull that outran the approach starts the fetch itself. */
+        const spendBar = () => {
+            clearDecay();
+            setPullModel(initialPull);
+            feedRef.current.holdEarlier();
+            feedRef.current.revealEarlier();
+        };
+        /** Upward travel at the top: bank it, and fire at the threshold. */
+        const travel = (px) => {
+            const kind = feedRef.current.earlier.kind;
+            // A pull at the start does nothing, and the frame does not bounce.
+            if (kind === "none")
+                return;
+            const result = advancePull(pullRef.current, { travel: px, atTop: scroller.scrollTop <= 0, now: Date.now() }, { threshold, decayMs });
+            setPullModel(result.model);
+            if (result.fire) {
+                spendBar();
+            }
+            else if (result.model.travel > 0) {
+                armDecay();
+            }
+            else {
+                clearDecay();
+            }
+        };
+        const readScroll = () => {
+            frameRef.current = null;
+            const next = frostOf(scroller.scrollTop, frostRange);
+            scroller.style.setProperty("--frost", String(next));
+            setFrost(next);
+            anchorRef.current = measureAnchor(scroller);
+            if (scroller.scrollTop > 0 && pullRef.current.travel > 0) {
+                clearDecay();
+                setPullModel(initialPull);
+            }
+            // Within one viewport of the top the next page is requested and held.
+            // Nothing is prepended on approach.
+            if (scroller.scrollTop <= scroller.clientHeight &&
+                feedRef.current.earlier.kind === "idle") {
+                feedRef.current.holdEarlier();
+            }
+        };
+        const onScroll = () => {
+            if (frameRef.current !== null)
+                return;
+            frameRef.current = window.requestAnimationFrame(readScroll);
+        };
+        const onWheel = (event) => {
+            if (scroller.scrollTop > 0) {
+                if (pullRef.current.travel > 0) {
+                    clearDecay();
+                    setPullModel(initialPull);
+                }
+                return;
+            }
+            if (event.deltaY < 0) {
+                // Not passive: the frame contains its own overscroll, so the window
+                // never rubber-bands while the reader spends the bar (§08).
+                event.preventDefault();
+                travel(-event.deltaY);
+            }
+            else if (pullRef.current.travel > 0) {
+                clearDecay();
+                setPullModel(initialPull);
+            }
+        };
+        let touchY = null;
+        const onTouchStart = (event) => {
+            touchY = event.touches[0]?.clientY ?? null;
+        };
+        const onTouchMove = (event) => {
+            const y = event.touches[0]?.clientY;
+            if (touchY === null || y === undefined || scroller.scrollTop > 0)
+                return;
+            const dy = y - touchY;
+            touchY = y;
+            if (dy > 0)
+                travel(dy);
+            else if (dy < 0 && pullRef.current.travel > 0) {
+                clearDecay();
+                setPullModel(initialPull);
+            }
+        };
+        const onTouchEnd = () => {
+            touchY = null;
+        };
+        // Home, PageUp and ↑ at the top reveal on one press (§08).
+        const onKeyDown = (event) => {
+            if (event.key !== "Home" && event.key !== "PageUp" && event.key !== "ArrowUp")
+                return;
+            if (scroller.scrollTop > 0)
+                return;
+            const kind = feedRef.current.earlier.kind;
+            if (kind === "none" || kind === "revealing")
+                return;
+            event.preventDefault();
+            spendBar();
+        };
+        scroller.addEventListener("scroll", onScroll, { passive: true });
+        scroller.addEventListener("wheel", onWheel, { passive: false });
+        scroller.addEventListener("touchstart", onTouchStart, { passive: true });
+        scroller.addEventListener("touchmove", onTouchMove, { passive: true });
+        scroller.addEventListener("touchend", onTouchEnd, { passive: true });
+        scroller.addEventListener("touchcancel", onTouchEnd, { passive: true });
+        scroller.addEventListener("keydown", onKeyDown);
+        readScroll();
+        return () => {
+            scroller.removeEventListener("scroll", onScroll);
+            scroller.removeEventListener("wheel", onWheel);
+            scroller.removeEventListener("touchstart", onTouchStart);
+            scroller.removeEventListener("touchmove", onTouchMove);
+            scroller.removeEventListener("touchend", onTouchEnd);
+            scroller.removeEventListener("touchcancel", onTouchEnd);
+            scroller.removeEventListener("keydown", onKeyDown);
+            if (frameRef.current !== null)
+                window.cancelAnimationFrame(frameRef.current);
+            frameRef.current = null;
+            clearDecay();
+            scroller.style.removeProperty("--frost");
+        };
+    }, [scrollerRef, enabled, threshold, decayMs, frostRange, setPullModel]);
+    // After a landing the reader may still be within a viewport of the top: the
+    // record re-approaches immediately so the next page is already held.
+    const earlierKind = feed.earlier.kind;
+    useEffect(() => {
+        if (!enabled || earlierKind !== "idle")
+            return;
+        const scroller = scrollerRef.current;
+        if (scroller === null)
+            return;
+        if (scroller.scrollTop <= scroller.clientHeight)
+            feedRef.current.holdEarlier();
+    }, [enabled, earlierKind, landSeq, scrollerRef]);
+    return { pull, frost, receipt };
+}