@khorsheed/dsh-room 0.2.2 → 0.2.3

package/lib/types/client/TeamView.js

@@ -0,0 +1,210 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The team view: the room's organization in the right sidebar, opened from
+ * the members tab. One layout that adapts to its own width — narrow, an
+ * indented tree (you → coordinator → members) whose nodes expand into the
+ * deliveries they received; wide (≥ 600px), the same tree laid out
+ * top-down with drawn edges (solid = tasks handed over, with the report
+ * count coming back; dashed = FYIs off the tree) and the selected member's
+ * details below. Opening it with a `member` param selects and reveals that
+ * member (the cards' 在团队中定位).
+ */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { formatDurationMs } from './format.js';
+import { memberColor } from './member-color.js';
+import { formatTokens, TEAM_ROOT, teamOf } from './team.js';
+import css from './TeamView.module.css';
+/** A node element by id, without building a selector from member ids. */
+function nodeElement(root, id) {
+    return [...root.querySelectorAll('[data-team-node]')].find(element => element.dataset['teamNode'] === id);
+}
+/** Wide layout threshold (the view's own width). */
+const WIDE = 600;
+function StatusDot({ node, t }) {
+    const label = node.status === 'running' ? t('members.status.running') : node.status === 'failed' ? t('members.status.failed') : t('members.status.idle');
+    return _jsxs("span", { className: css.status, "data-status": node.status, children: [_jsx("i", { "aria-hidden": true }), label] });
+}
+function Avatar({ node }) {
+    return _jsx("span", { className: css.avatar, style: { '--member-color': memberColor(node.member.name) }, "aria-hidden": true, children: node.member.name.slice(0, 1).toUpperCase() });
+}
+/** Provider · model line (an outside session: what it is and how often it was asked). */
+function configLine(node, t) {
+    if (node.external !== undefined) {
+        return [t(node.external.room ? 'team.external.room' : 'team.external.session'), ...node.external.helps.length === 0 ? [] : [t('team.external.asks', { count: node.external.helps.length })]].join(' · ');
+    }
+    const provider = node.member.kind === 'main-agent' ? t('member.kind.main')
+        : node.member.kind === 'native' ? t('member.kind.native', { preset: node.member.preset ?? t('member.kind.defaultPreset') })
+            : node.member.provider ?? '';
+    return [provider, node.model].filter(Boolean).join(' · ');
+}
+function statsLine(node, t) {
+    return t('team.stats', { tokens: formatTokens(node.tokens), time: formatDurationMs(node.elapsedMs), rounds: node.rounds });
+}
+/** What flowed into a node: tasks and returned reports from its parent, FYIs, and work from elsewhere. */
+function flowOf(team, node, t) {
+    const name = (id) => id === TEAM_ROOT ? t('team.you') : team.nodes.find(entry => entry.id === id)?.member.name ?? id;
+    const into = team.edges.filter(edge => edge.to === node.id);
+    const fromParent = into.find(edge => edge.from === node.parent);
+    const others = into.filter(edge => edge.from !== node.parent && edge.tasks > 0)
+        .map(edge => t('team.crossTask', { from: name(edge.from), count: edge.tasks }));
+    return {
+        tasks: fromParent?.tasks ?? 0,
+        reports: fromParent?.reports ?? 0,
+        notifies: into.reduce((sum, edge) => sum + edge.notifies, 0),
+        others: others.length === 0 ? undefined : others.join(' · '),
+    };
+}
+/** The counts pill: 「派 3 · 回 2 · 知会 1」, other sources in its tooltip. */
+function FlowPill({ team, node, t, floating }) {
+    if (node.parent === TEAM_ROOT && node.coordinator)
+        return null;
+    const flow = flowOf(team, node, t);
+    if (flow.tasks === 0 && flow.notifies === 0 && flow.others === undefined)
+        return null;
+    return (_jsxs("span", { className: floating ? css.pillFloat : css.pill, title: flow.others === undefined ? undefined : t('team.alsoFrom', { list: flow.others }), children: [t('team.pillTasks', { count: flow.tasks }), flow.reports > 0 && _jsx("span", { className: css.pillReport, children: t('team.pillReports', { count: flow.reports }) }), flow.notifies > 0 && _jsx("span", { className: css.pillNotify, children: t('team.pillNotify', { count: flow.notifies }) }), flow.others !== undefined && _jsx("span", { children: "\u2026" })] }));
+}
+function Deliveries({ node, t }) {
+    if (node.deliveries.length === 0)
+        return _jsx("p", { className: css.empty, children: t('team.noDeliveries') });
+    return (_jsx("ul", { className: css.deliveries, children: node.deliveries.slice(0, 20).map(delivery => (_jsxs("li", { children: [_jsxs("span", { className: css.msgId, children: ["#m", delivery.seq] }), _jsx("span", { className: css.from, children: delivery.kind === 'report'
+                        ? t('team.kind.report')
+                        : t(delivery.kind === 'notify' ? 'team.fromNotify' : 'team.from', { from: delivery.from === TEAM_ROOT ? t('team.you') : delivery.from }) }), _jsx("span", { className: css.text, title: delivery.text, children: delivery.text }), _jsx("span", { className: css.outcome, "data-status": delivery.status, children: t(`team.status.${delivery.status}`) })] }, delivery.id))) }));
+}
+function NodeCard({ team, node, selected, onSelect, t, compact }) {
+    return (_jsxs("button", { type: "button", className: css.node, "data-selected": selected, "data-team-node": node.id, "data-external": node.external === undefined ? undefined : node.external.linked ? 'linked' : 'helper', "data-done": node.external?.done === true && !node.external.linked ? '' : undefined, onClick: onSelect, "aria-expanded": compact ? selected : undefined, children: [!compact && node.external === undefined && _jsx(FlowPill, { team: team, node: node, t: t, floating: true }), _jsxs("span", { className: css.nodeHead, children: [_jsx(Avatar, { node: node }), _jsx("span", { className: css.nodeName, children: node.member.name }), node.coordinator && _jsx("span", { className: css.chip, children: t('coordinator.label') }), node.external !== undefined && _jsx("span", { className: css.chip, "data-external": "", children: t(node.external.linked ? 'team.external.linked' : 'team.external.helper') }), node.member.role !== undefined && _jsx("span", { className: css.role, children: node.member.role }), _jsx(StatusDot, { node: node, t: t })] }), _jsx("span", { className: css.line, children: configLine(node, t) }), node.external === undefined && (_jsxs("span", { className: css.line, children: [compact && _jsx(FlowPill, { team: team, node: node, t: t, floating: false }), _jsx("span", { children: statsLine(node, t) })] })), node.current !== undefined && _jsxs("span", { className: css.current, children: ["\u25B6 ", node.current] })] }));
+}
+/** An outside session's list control: 加入房间成员 (a plain session asked before) or 移出成员列表. */
+function LinkControl({ node, linkSession, unlinkSession, t }) {
+    const external = node.external;
+    if (external === undefined || external.room)
+        return null;
+    if (external.linked) {
+        return unlinkSession === undefined ? null : _jsx("button", { type: "button", className: css.open, onClick: () => { unlinkSession(external.sessionId); }, children: t('team.external.unlink') });
+    }
+    return linkSession === undefined ? null : _jsx("button", { type: "button", className: css.open, onClick: () => { linkSession(external.sessionId, node.member.name); }, children: t('team.external.link') });
+}
+function Tree({ team, at, selected, onSelect, openSession, linkSession, unlinkSession, t }) {
+    const children = team.nodes.filter(node => node.parent === at);
+    if (children.length === 0)
+        return null;
+    return (_jsx("ul", { className: css.tree, children: children.map(node => (_jsxs("li", { children: [_jsx(NodeCard, { team: team, node: node, selected: selected === node.id, compact: true, onSelect: () => { onSelect(node.id); }, t: t }), selected === node.id && (_jsxs("div", { className: css.expand, children: [_jsx(Deliveries, { node: node, t: t }), node.member.childSessionId !== undefined && (_jsx("button", { type: "button", className: css.open, onClick: () => { openSession(node.member.childSessionId); }, children: t('team.openSession') })), _jsx(LinkControl, { node: node, linkSession: linkSession, unlinkSession: unlinkSession, t: t })] })), _jsx(Tree, { team: team, at: node.id, selected: selected, onSelect: onSelect, openSession: openSession, linkSession: linkSession, unlinkSession: unlinkSession, t: t })] }, node.id))) }));
+}
+/** Depth levels for the wide layout. */
+function levels(team) {
+    const rows = [[TEAM_ROOT]];
+    let frontier = [TEAM_ROOT];
+    while (frontier.length > 0) {
+        const next = team.nodes.filter(node => frontier.includes(node.parent)).map(node => node.id);
+        if (next.length > 0)
+            rows.push(next);
+        frontier = next;
+    }
+    return rows;
+}
+/** Node width plus gap in the wide layout (matches the stylesheet). */
+const SLOT = 210 + 16;
+/**
+ * The wide layout: one row per depth, connected trunk-and-branch — a trunk
+ * down from each parent, one horizontal bus over its children, a short drop
+ * to each child — so lines never cross and carry no text; the counts ride
+ * each node's pill. A row wider than the panel folds its tail into 「+N」.
+ */
+function Graph({ team, selected, onSelect, t }) {
+    const ref = useRef(null);
+    const [paths, setPaths] = useState([]);
+    const [width, setWidth] = useState(0);
+    const [unfolded, setUnfolded] = useState(new Set());
+    const rows = useMemo(() => levels(team), [team]);
+    const perRow = Math.max(2, Math.floor((width + 16) / SLOT));
+    useLayoutEffect(() => {
+        const root = ref.current;
+        if (root === null)
+            return undefined;
+        const draw = () => {
+            setWidth(root.clientWidth);
+            const base = root.getBoundingClientRect();
+            const box = (id) => {
+                const element = nodeElement(root, id);
+                if (element === undefined)
+                    return undefined;
+                const rect = element.getBoundingClientRect();
+                return { x: rect.left - base.left, y: rect.top - base.top, w: rect.width, h: rect.height };
+            };
+            const next = [];
+            const parents = new Set(team.nodes.map(node => node.parent));
+            for (const parent of parents) {
+                const from = box(parent);
+                const kids = team.nodes.filter(node => node.parent === parent).map(node => box(node.id)).filter(entry => entry !== undefined);
+                const more = nodeElement(root, `more:${parent}`);
+                if (more !== undefined) {
+                    const rect = more.getBoundingClientRect();
+                    kids.push({ x: rect.left - base.left, y: rect.top - base.top, w: rect.width, h: rect.height });
+                }
+                if (from === undefined || kids.length === 0)
+                    continue;
+                const top = Math.min(...kids.map(kid => kid.y));
+                const bus = top - 16;
+                const px = from.x + from.w / 2;
+                next.push({ d: `M${px},${from.y + from.h} V${bus}`, drop: false });
+                const xs = kids.map(kid => kid.x + kid.w / 2);
+                next.push({ d: `M${Math.min(px, ...xs)},${bus} H${Math.max(px, ...xs)}`, drop: false });
+                for (const [index, kid] of kids.entries())
+                    next.push({ d: `M${xs[index]},${bus} V${kid.y - 2}`, drop: true });
+            }
+            setPaths(next);
+        };
+        draw();
+        const observer = new ResizeObserver(draw);
+        observer.observe(root);
+        return () => { observer.disconnect(); };
+    }, [team, unfolded, perRow]);
+    return (_jsxs("div", { className: css.graph, ref: ref, children: [_jsxs("svg", { className: css.edges, "aria-hidden": true, children: [_jsx("defs", { children: _jsx("marker", { id: "room-team-arrow", viewBox: "0 0 8 8", refX: "7", refY: "4", markerWidth: "6", markerHeight: "6", orient: "auto", children: _jsx("path", { d: "M0,0 L8,4 L0,8 z", className: css.arrow }) }) }), paths.map((path, index) => _jsx("path", { d: path.d, className: css.edgeTask, markerEnd: path.drop ? 'url(#room-team-arrow)' : undefined }, index))] }), rows.map((row, index) => {
+                const folds = row.length > perRow && !unfolded.has(index);
+                const shown = folds ? row.slice(0, perRow - 1) : row;
+                // One 「+N」 per row, attached to the parent of the first hidden node (the bus already spans it).
+                const hidden = folds ? row.slice(perRow - 1) : [];
+                const parentOfHidden = hidden.length === 0 ? undefined : team.nodes.find(node => node.id === hidden[0])?.parent;
+                return (_jsxs("div", { className: css.level, children: [shown.map((id) => {
+                            if (id === TEAM_ROOT)
+                                return _jsx("span", { className: css.root, "data-team-node": TEAM_ROOT, children: t('team.you') }, id);
+                            const node = team.nodes.find(entry => entry.id === id);
+                            return _jsx(NodeCard, { team: team, node: node, selected: selected === id, compact: false, onSelect: () => { onSelect(id); }, t: t }, id);
+                        }), hidden.length > 0 && (_jsx("button", { type: "button", className: css.more, "data-team-node": `more:${parentOfHidden}`, onClick: () => { setUnfolded(current => new Set([...current, index])); }, children: t('team.more', { count: hidden.length }) }))] }, index));
+            })] }));
+}
+/** The team view body. */
+export function TeamView({ state, focus, openSession, linkSession, unlinkSession, t }) {
+    const team = useMemo(() => teamOf(state), [state]);
+    const rootRef = useRef(null);
+    const [wide, setWide] = useState(false);
+    const [selected, setSelected] = useState(undefined);
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        if (root === null)
+            return undefined;
+        const observer = new ResizeObserver(() => { setWide(root.clientWidth >= WIDE); });
+        observer.observe(root);
+        setWide(root.clientWidth >= WIDE);
+        return () => { observer.disconnect(); };
+    }, []);
+    useEffect(() => {
+        if (focus === undefined)
+            return;
+        const node = team.nodes.find(entry => entry.member.name === focus.member);
+        if (node === undefined)
+            return;
+        setSelected(node.id);
+        requestAnimationFrame(() => {
+            const root = rootRef.current;
+            if (root !== null)
+                nodeElement(root, node.id)?.scrollIntoView({ block: 'nearest' });
+        });
+        // Every navigation reveals again, even to the same member.
+    }, [focus?.member, focus?.revision]);
+    const select = (id) => { setSelected(current => current === id && !wide ? undefined : id); };
+    const chosen = team.nodes.find(node => node.id === selected);
+    return (_jsxs("div", { className: css.team, ref: rootRef, children: [_jsx("p", { className: css.summary, children: t('team.summary', {
+                    members: team.totals.members, running: team.totals.running, deliveries: team.totals.deliveries,
+                    tokens: formatTokens(team.totals.tokens), time: formatDurationMs(team.totals.elapsedMs),
+                }) }), _jsx("p", { className: css.legend, children: _jsx("span", { children: t('team.legend.pill') }) }), wide ? (_jsxs(_Fragment, { children: [_jsx(Graph, { team: team, selected: selected, onSelect: select, t: t }), chosen === undefined ? _jsx("p", { className: css.empty, children: t('team.pick') }) : (_jsxs("section", { className: css.detail, children: [_jsxs("div", { className: css.nodeHead, children: [_jsx(Avatar, { node: chosen }), _jsx("span", { className: css.nodeName, children: chosen.member.name }), chosen.member.role !== undefined && _jsx("span", { className: css.role, children: chosen.member.role }), _jsx(StatusDot, { node: chosen, t: t }), chosen.member.childSessionId !== undefined && (_jsx("button", { type: "button", className: css.open, onClick: () => { openSession(chosen.member.childSessionId); }, children: t('team.openSession') })), _jsx(LinkControl, { node: chosen, linkSession: linkSession, unlinkSession: unlinkSession, t: t })] }), _jsxs("p", { className: css.line, children: [configLine(chosen, t), chosen.external === undefined ? ` · ${statsLine(chosen, t)}` : ''] }), chosen.external !== undefined && _jsx("p", { className: css.line, children: t('team.external.note') }), _jsx(Deliveries, { node: chosen, t: t })] }))] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: css.root, children: t('team.you') }), _jsx(Tree, { team: team, at: TEAM_ROOT, selected: selected, onSelect: select, openSession: openSession, linkSession: linkSession, unlinkSession: unlinkSession, t: t })] }))] }));
+}

package/lib/types/client/at-menu.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The room composer's @ menu, data side: two groups — this room's members,
+ * then other sessions (the host's session-reference candidates, the same
+ * list its own @ menu shows). With nothing typed the second group lists the
+ * five most recent; typing filters both groups by a fuzzy match where the
+ * typed characters only have to appear in order (「剪插」 finds 「开发剪辑插件」),
+ * ranked exact > prefix > contiguous > in-order, then by recency.
+ *
+ * Pure and DOM-free — unit-tested on its own.
+ * @module @khorsheed/dsh-room/client/at-menu
+ */
+/** One session candidate, as the host's session-reference resolver lists it. */
+export interface SessionCandidate {
+    readonly sessionId: string;
+    /** The latest title (the session id when untitled). */
+    readonly label: string;
+    readonly displayTitle?: string;
+    /** The canonical `@[label](dsh-session:…)` mention the host inserts. */
+    readonly mention: string;
+    readonly sameWorkspace?: boolean;
+    readonly createdAt?: number;
+    /** The session is a room (asking a room goes through its own roster). */
+    readonly room?: boolean;
+    /** A room's members (askable by name). */
+    readonly members?: readonly RoomMenuMember[];
+    /** On this room's member list (「加入房间成员」). */
+    readonly linked?: boolean;
+}
+/** A member of another room, as the @ menu lists it. */
+export interface RoomMenuMember {
+    readonly name: string;
+    readonly kind: string;
+    readonly provider?: string;
+}
+/** One row of the other-sessions group: a session (or room), or a member of a room. */
+export type OtherRow = {
+    readonly kind: 'session';
+    readonly candidate: SessionCandidate;
+} | {
+    readonly kind: 'roomMember';
+    readonly candidate: SessionCandidate;
+    readonly member: RoomMenuMember;
+    readonly nested?: true;
+};
+/** How many other sessions show before anything is typed. */
+export declare const RECENT_SESSIONS = 5;
+/** How many other sessions a typed query shows at most. */
+export declare const MATCHED_SESSIONS = 8;
+/**
+ * How well a query matches a text: 0 exact, 1 prefix, 2 contiguous, 3 the
+ * characters in order; undefined for no match. Case-insensitive; an empty
+ * query matches everything at tier 0.
+ * @param query - what the human typed after `@`.
+ * @param text - a member name or session title.
+ * @returns the tier, or undefined.
+ */
+export declare function matchTier(query: string, text: string): number | undefined;
+/**
+ * Filter and rank by match tier, keeping the incoming order (recency) within a tier.
+ * @param query - what the human typed after `@`.
+ * @param items - the candidates, most relevant first.
+ * @param text - the text an item is matched on.
+ * @returns the matching items, best first.
+ */
+export declare function rankByMatch<T>(query: string, items: readonly T[], text: (item: T) => string): T[];
+/** A session candidate's shown title. */
+export declare function sessionTitle(candidate: SessionCandidate): string;
+/**
+ * The other-sessions group: the candidates minus this room and its members'
+ * own sessions, deduplicated, then the recent five (nothing typed) or the
+ * best matches.
+ * @param query - what the human typed after `@`.
+ * @param candidates - the resolver's candidates, most relevant first (several lookups may be merged).
+ * @param exclude - session ids never offered (the room, its members' sessions).
+ * @returns the group's rows.
+ */
+export declare function sessionRows(query: string, candidates: readonly SessionCandidate[], exclude: ReadonlySet<string>): SessionCandidate[];
+/**
+ * The other-sessions group with rooms. Nothing typed: the recent five, each
+ * expanded room followed by its members. Typed: sessions and every room's
+ * members match together (a member by its own name), best first.
+ * @param query - what the human typed after `@`.
+ * @param candidates - the resolver's candidates, most relevant first.
+ * @param exclude - session ids never offered.
+ * @param expanded - the rooms whose members show.
+ * @returns the group's rows.
+ */
+export declare function otherRows(query: string, candidates: readonly SessionCandidate[], exclude: ReadonlySet<string>, expanded: ReadonlySet<string>): OtherRow[];
+/**
+ * The mention for a member of a room: the room's own `dsh-session:` URI under
+ * a 「成员（房间）」 label (the label `room_help` reads the member from).
+ * @param candidate - the room.
+ * @param member - its member.
+ * @returns the mention text and its label.
+ */
+export declare function memberMention(candidate: SessionCandidate, member: RoomMenuMember): {
+    readonly mention: string;
+    readonly label: string;
+};
+/**
+ * The host's canonical mention of a session: `@[label](dsh-session:…)`, the
+ * URI being base64url of the JSON-encoded id (what the host's own @ menu
+ * writes; built here for the room's linked sessions, which the resolver's
+ * recent list may not carry).
+ * @param sessionId - the session.
+ * @param label - its shown title.
+ * @returns the mention text.
+ */
+export declare function sessionMention(sessionId: string, label: string): string;
+/**
+ * A free-text offset in the composer's textarea as a detect-coordinate
+ * offset in the input machine's draft: each chip before it folds to one
+ * placeholder (see draft-chips.ts), so the offset moves right by the number
+ * of chips whose segments end before it.
+ * @param segments - the typed text around the chips (draftSegments).
+ * @param freeIndex - the offset in the textarea's text.
+ * @returns the detect offset.
+ */
+export declare function detectOffset(segments: readonly string[], freeIndex: number): number;
+/**
+ * A row's time hint: HH:MM today, else M/D.
+ * @param at - epoch ms.
+ * @param now - epoch ms of "now".
+ * @returns the hint.
+ */
+export declare function shortTime(at: number, now: number): string;
+//# sourceMappingURL=at-menu.d.ts.map

package/lib/types/client/at-menu.js

@@ -0,0 +1,173 @@
+/**
+ * The room composer's @ menu, data side: two groups — this room's members,
+ * then other sessions (the host's session-reference candidates, the same
+ * list its own @ menu shows). With nothing typed the second group lists the
+ * five most recent; typing filters both groups by a fuzzy match where the
+ * typed characters only have to appear in order (「剪插」 finds 「开发剪辑插件」),
+ * ranked exact > prefix > contiguous > in-order, then by recency.
+ *
+ * Pure and DOM-free — unit-tested on its own.
+ * @module @khorsheed/dsh-room/client/at-menu
+ */
+/** How many other sessions show before anything is typed. */
+export const RECENT_SESSIONS = 5;
+/** How many other sessions a typed query shows at most. */
+export const MATCHED_SESSIONS = 8;
+/**
+ * How well a query matches a text: 0 exact, 1 prefix, 2 contiguous, 3 the
+ * characters in order; undefined for no match. Case-insensitive; an empty
+ * query matches everything at tier 0.
+ * @param query - what the human typed after `@`.
+ * @param text - a member name or session title.
+ * @returns the tier, or undefined.
+ */
+export function matchTier(query, text) {
+    const needle = query.toLocaleLowerCase();
+    const haystack = text.toLocaleLowerCase();
+    if (needle === '' || haystack === needle)
+        return 0;
+    if (haystack.startsWith(needle))
+        return 1;
+    if (haystack.includes(needle))
+        return 2;
+    let at = 0;
+    for (const char of haystack) {
+        if (char === needle[at])
+            at += 1;
+        if (at === needle.length)
+            return 3;
+    }
+    return undefined;
+}
+/**
+ * Filter and rank by match tier, keeping the incoming order (recency) within a tier.
+ * @param query - what the human typed after `@`.
+ * @param items - the candidates, most relevant first.
+ * @param text - the text an item is matched on.
+ * @returns the matching items, best first.
+ */
+export function rankByMatch(query, items, text) {
+    return items
+        .map((item, index) => ({ item, index, tier: matchTier(query, text(item)) }))
+        .filter((entry) => entry.tier !== undefined)
+        .sort((a, b) => a.tier - b.tier || a.index - b.index)
+        .map(entry => entry.item);
+}
+/** A session candidate's shown title. */
+export function sessionTitle(candidate) {
+    return candidate.displayTitle ?? candidate.label;
+}
+/**
+ * The other-sessions group: the candidates minus this room and its members'
+ * own sessions, deduplicated, then the recent five (nothing typed) or the
+ * best matches.
+ * @param query - what the human typed after `@`.
+ * @param candidates - the resolver's candidates, most relevant first (several lookups may be merged).
+ * @param exclude - session ids never offered (the room, its members' sessions).
+ * @returns the group's rows.
+ */
+export function sessionRows(query, candidates, exclude) {
+    const pool = uniqueCandidates(candidates, exclude);
+    if (query === '')
+        return pool.slice(0, RECENT_SESSIONS);
+    return rankByMatch(query, pool, sessionTitle).slice(0, MATCHED_SESSIONS);
+}
+/** The candidates minus the excluded, first occurrence kept. */
+function uniqueCandidates(candidates, exclude) {
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        if (exclude.has(candidate.sessionId) || seen.has(candidate.sessionId))
+            return false;
+        seen.add(candidate.sessionId);
+        return true;
+    });
+}
+/**
+ * The other-sessions group with rooms. Nothing typed: the recent five, each
+ * expanded room followed by its members. Typed: sessions and every room's
+ * members match together (a member by its own name), best first.
+ * @param query - what the human typed after `@`.
+ * @param candidates - the resolver's candidates, most relevant first.
+ * @param exclude - session ids never offered.
+ * @param expanded - the rooms whose members show.
+ * @returns the group's rows.
+ */
+export function otherRows(query, candidates, exclude, expanded) {
+    if (query === '') {
+        return sessionRows('', candidates, exclude).flatMap(candidate => [
+            { kind: 'session', candidate },
+            ...expanded.has(candidate.sessionId) ? (candidate.members ?? []).map(member => ({ kind: 'roomMember', candidate, member, nested: true })) : [],
+        ]);
+    }
+    const pool = uniqueCandidates(candidates, exclude).flatMap(candidate => [
+        { kind: 'session', candidate },
+        ...(candidate.members ?? []).map(member => ({ kind: 'roomMember', candidate, member })),
+    ]);
+    const ranked = rankByMatch(query, pool, row => row.kind === 'session' ? sessionTitle(row.candidate) : row.member.name).slice(0, MATCHED_SESSIONS);
+    // An expanded room lists all its members under it, matched or not (a
+    // member already listed by its own match moves under its room).
+    const under = (row) => row.kind === 'roomMember' && expanded.has(row.candidate.sessionId);
+    return ranked.filter(row => !under(row) || !ranked.some(other => other.kind === 'session' && other.candidate.sessionId === row.candidate.sessionId))
+        .flatMap(row => row.kind === 'session' && expanded.has(row.candidate.sessionId)
+        ? [row, ...(row.candidate.members ?? []).map(member => ({ kind: 'roomMember', candidate: row.candidate, member, nested: true }))]
+        : [row]);
+}
+/**
+ * The mention for a member of a room: the room's own `dsh-session:` URI under
+ * a 「成员（房间）」 label (the label `room_help` reads the member from).
+ * @param candidate - the room.
+ * @param member - its member.
+ * @returns the mention text and its label.
+ */
+export function memberMention(candidate, member) {
+    const uri = /\]\((dsh-session:[^)\s]*)\)\s*$/u.exec(candidate.mention)?.[1] ?? '';
+    const label = `${member.name}（${sessionTitle(candidate)}）`;
+    return { mention: `@[${label.replace(/[\\\]]/gu, '\\$&')}](${uri})`, label };
+}
+/**
+ * The host's canonical mention of a session: `@[label](dsh-session:…)`, the
+ * URI being base64url of the JSON-encoded id (what the host's own @ menu
+ * writes; built here for the room's linked sessions, which the resolver's
+ * recent list may not carry).
+ * @param sessionId - the session.
+ * @param label - its shown title.
+ * @returns the mention text.
+ */
+export function sessionMention(sessionId, label) {
+    const bytes = new TextEncoder().encode(JSON.stringify(sessionId));
+    const payload = btoa(String.fromCharCode(...bytes)).replace(/\+/gu, '-').replace(/\//gu, '_').replace(/=+$/u, '');
+    return `@[${label.replace(/[\\\]]/gu, '\\$&')}](dsh-session:${payload})`;
+}
+/**
+ * A free-text offset in the composer's textarea as a detect-coordinate
+ * offset in the input machine's draft: each chip before it folds to one
+ * placeholder (see draft-chips.ts), so the offset moves right by the number
+ * of chips whose segments end before it.
+ * @param segments - the typed text around the chips (draftSegments).
+ * @param freeIndex - the offset in the textarea's text.
+ * @returns the detect offset.
+ */
+export function detectOffset(segments, freeIndex) {
+    let remaining = freeIndex;
+    for (let k = 0; k < segments.length; k += 1) {
+        const length = segments[k].length;
+        if (remaining <= length || k === segments.length - 1)
+            return freeIndex + k;
+        remaining -= length;
+    }
+    return freeIndex;
+}
+/**
+ * A row's time hint: HH:MM today, else M/D.
+ * @param at - epoch ms.
+ * @param now - epoch ms of "now".
+ * @returns the hint.
+ */
+export function shortTime(at, now) {
+    const date = new Date(at);
+    const today = new Date(now);
+    if (date.toDateString() === today.toDateString()) {
+        return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+    }
+    return `${date.getMonth() + 1}/${date.getDate()}`;
+}

package/lib/types/client/draft-chips.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Reference chips in the room composer's plain textarea. The draft lives in
+ * the session's official input machine (RoomComposer's module header), whose
+ * `draft` is the CLIPBOARD projection — each chip expanded to the full text
+ * it sends (a quote chip: its whole `> ` block). A textarea showing that
+ * projection shows raw wire text, and editing it through `setDraft` flattens
+ * every chip. So the composer shows chips as their own row and the textarea
+ * only the typed text BETWEEN them; an edit is mapped back onto the machine
+ * as detect-coordinate replacements (`insertText`), which never touch a chip
+ * outside the edited range.
+ *
+ * Coordinates: the machine's spans speak the DETECT projection, where each
+ * chip folds to one placeholder character. With chips at clipboard offsets,
+ * the typed text splits into segments around them; free-text index `i` in
+ * segment `k` sits at detect index `i + k` (k chips precede it).
+ *
+ * Pure and DOM-free — unit-tested on its own.
+ * @module @khorsheed/dsh-room/client/draft-chips
+ */
+/** One reference chip of the input machine (the host's Occurrence, mirrored to the fields used). */
+export interface DraftChip {
+    /** Shell-assigned stable identity. */
+    readonly occurrenceId: number;
+    /** Owning trigger source (the preview route's key). */
+    readonly source: string;
+    /** Owner-scoped reference payload. */
+    readonly ref: string;
+    /** Offset in the clipboard projection. */
+    readonly offset: number;
+    /** Length in the clipboard projection. */
+    readonly length: number;
+    /** Inline display label. */
+    readonly label: string;
+}
+/** One detect-coordinate replacement (empty text deletes). */
+export interface DraftEdit {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+}
+/**
+ * The typed text around the chips: one segment before each chip plus the
+ * tail, in order (so `segments.length === chips.length + 1`).
+ * @param draft - the clipboard projection.
+ * @param chips - the machine's chips, sorted by offset.
+ */
+export declare function draftSegments(draft: string, chips: readonly DraftChip[]): string[];
+/** The textarea's text: the draft with every chip's clipboard text removed. */
+export declare function freeText(draft: string, chips: readonly DraftChip[]): string;
+/** The detect index of chip `k` (its single placeholder character). */
+export declare function chipDetectIndex(draft: string, chips: readonly DraftChip[], k: number): number;
+/**
+ * Plan the machine edits turning the current free text into `next` while
+ * keeping every chip. The change is the span between the common prefix and
+ * suffix; its replacement lands in the segment where it starts (a caret on a
+ * chip boundary types BEFORE the chip, which keeps a quote block's
+ * attribution line closed), and any part of the old span in later segments
+ * is deleted segment by segment — a range swept across a chip never deletes
+ * the chip itself. Edits are ordered last-first, so applying them in order
+ * keeps every earlier coordinate valid.
+ * @param draft - the clipboard projection.
+ * @param chips - the machine's chips, sorted by offset.
+ * @param next - the textarea's new value.
+ * @returns the edits to apply in order (empty when nothing changed).
+ */
+export declare function planFreeEdit(draft: string, chips: readonly DraftChip[], next: string): DraftEdit[];
+//# sourceMappingURL=draft-chips.d.ts.map