oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/dev/client/connectivity/session-navigation-intent.mjs

@@ -0,0 +1,189 @@
+export const SESSION_CHAT_NAVIGATION_OUTCOMES = Object.freeze({
+  NOOP_EQUIVALENT: "noop_equivalent",
+  SAME_SESSION_CONTEXT_NAVIGATION: "same_session_context_navigation",
+  CROSS_SESSION_TRANSITION: "cross_session_transition",
+  DOCUMENT_HANDOFF: "document_handoff",
+  INVALID_OR_STALE: "invalid_or_stale",
+});
+
+const SESSION_APP_PREFIX = "/app/sessions";
+const DEFAULT_PAGE = "chat";
+const SUPPORTED_SESSION_PAGES = new Set([
+  "chat",
+  "profile",
+  "loop",
+  "explorer",
+  "file-preview",
+]);
+const SEMANTIC_QUERY_KEYS = new Set(["focus_event_id"]);
+
+function normalizedText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function decodePathPart(value) {
+  try {
+    return normalizedText(decodeURIComponent(value));
+  } catch {
+    return "";
+  }
+}
+
+export function normalizeSessionChatNavigationIntent(input = {}) {
+  const sessionId = normalizedText(input.sessionId);
+  const page = normalizedText(input.page) || DEFAULT_PAGE;
+  const source = normalizedText(input.source) || "unknown";
+  const historyPolicy = normalizedText(input.historyPolicy) || "push";
+  const documentHandoff = input.documentHandoff === true;
+  if (documentHandoff) {
+    return {
+      valid: true,
+      documentHandoff: true,
+      sessionId,
+      page,
+      semantic: {},
+      explicitSemanticKeys: [],
+      source,
+      historyPolicy,
+    };
+  }
+  if (!sessionId || !SUPPORTED_SESSION_PAGES.has(page)) {
+    return {
+      valid: false,
+      documentHandoff: false,
+      sessionId,
+      page,
+      semantic: {},
+      explicitSemanticKeys: [],
+      source,
+      historyPolicy,
+    };
+  }
+
+  const semantic = {};
+  const explicitSemanticKeys = [];
+  const semanticInput =
+    input.semantic && typeof input.semantic === "object" ? input.semantic : {};
+  for (const key of SEMANTIC_QUERY_KEYS) {
+    const value = normalizedText(semanticInput[key]);
+    if (!value) continue;
+    semantic[key] = value;
+    explicitSemanticKeys.push(key);
+  }
+  return {
+    valid: true,
+    documentHandoff: false,
+    sessionId,
+    page,
+    semantic,
+    explicitSemanticKeys,
+    source,
+    historyPolicy,
+  };
+}
+
+export function parseSessionChatNavigationIntent(
+  urlValue,
+  { source = "route", historyPolicy = "push", documentHandoff = false } = {}
+) {
+  let url;
+  try {
+    url = new URL(urlValue, "http://oysterun.invalid");
+  } catch {
+    return normalizeSessionChatNavigationIntent({ source, historyPolicy });
+  }
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length !== 4 || parts[0] !== "app" || parts[1] !== "sessions") {
+    return normalizeSessionChatNavigationIntent({
+      source,
+      historyPolicy,
+      documentHandoff,
+    });
+  }
+  const sessionId = decodePathPart(parts[2]);
+  const page = normalizedText(parts[3]);
+  const semantic = {};
+  for (const key of SEMANTIC_QUERY_KEYS) {
+    const value = normalizedText(url.searchParams.get(key));
+    if (value) semantic[key] = value;
+  }
+  return normalizeSessionChatNavigationIntent({
+    sessionId,
+    page,
+    semantic,
+    source,
+    historyPolicy,
+    documentHandoff,
+  });
+}
+
+export function classifySessionChatNavigation({ committed, target } = {}) {
+  if (!committed?.valid || !target?.valid) {
+    return SESSION_CHAT_NAVIGATION_OUTCOMES.INVALID_OR_STALE;
+  }
+  if (committed.documentHandoff || target.documentHandoff) {
+    return SESSION_CHAT_NAVIGATION_OUTCOMES.DOCUMENT_HANDOFF;
+  }
+  if (committed.sessionId !== target.sessionId) {
+    return SESSION_CHAT_NAVIGATION_OUTCOMES.CROSS_SESSION_TRANSITION;
+  }
+  if (committed.page !== target.page) {
+    return SESSION_CHAT_NAVIGATION_OUTCOMES.SAME_SESSION_CONTEXT_NAVIGATION;
+  }
+  for (const key of target.explicitSemanticKeys) {
+    if (target.semantic[key] !== committed.semantic[key]) {
+      return SESSION_CHAT_NAVIGATION_OUTCOMES.SAME_SESSION_CONTEXT_NAVIGATION;
+    }
+  }
+  return SESSION_CHAT_NAVIGATION_OUTCOMES.NOOP_EQUIVALENT;
+}
+
+export function classifySessionChatNavigationFromUrls({
+  committedSessionId,
+  currentUrl,
+  targetUrl,
+  source = "route",
+  historyPolicy = "push",
+  documentHandoff = false,
+} = {}) {
+  const committedFromUrl = parseSessionChatNavigationIntent(currentUrl, {
+    source: "committed_binding",
+    historyPolicy: "preserve",
+  });
+  const committed = normalizeSessionChatNavigationIntent({
+    ...committedFromUrl,
+    sessionId: normalizedText(committedSessionId),
+  });
+  const target = parseSessionChatNavigationIntent(targetUrl, {
+    source,
+    historyPolicy,
+    documentHandoff,
+  });
+  return classifySessionChatNavigation({ committed, target });
+}
+
+export function buildNormalizedSessionChatPath(
+  sessionId,
+  { focusEventId } = {}
+) {
+  const intent = normalizeSessionChatNavigationIntent({
+    sessionId,
+    page: DEFAULT_PAGE,
+    semantic: { focus_event_id: focusEventId },
+    source: "route_builder",
+    historyPolicy: "push",
+  });
+  if (!intent.valid) {
+    throw new Error("Session Chat path requires a valid Session id.");
+  }
+  const url = new URL(
+    `${SESSION_APP_PREFIX}/${encodeURIComponent(intent.sessionId)}/${
+      intent.page
+    }`,
+    "http://oysterun.invalid"
+  );
+  if (intent.semantic.focus_event_id) {
+    url.searchParams.set("focus_event_id", intent.semantic.focus_event_id);
+  }
+  return `${url.pathname}${url.search}`;
+}

package/dev/client/connectivity/session-transition-state.mjs

@@ -1,3 +1,9 @@
+import {
+  buildNormalizedSessionChatPath,
+  classifySessionChatNavigationFromUrls,
+  SESSION_CHAT_NAVIGATION_OUTCOMES,
+} from "./session-navigation-intent.mjs";
+
 export const OYSTERUN_SESSION_TRANSITION_SCHEMA =
   "routec.p217_session_transition.v1";
 export const OYSTERUN_SESSION_TRANSITION_VERIFICATION_DELAY_PARAM =
@@ -89,18 +95,24 @@ export function sessionIdFromCleanChatPath(pathname) {
 }
 
 export function cleanSessionChatPath(sessionId) {
-  const normalized = String(sessionId || "").trim();
-  if (!normalized)
-    throw new Error("Session transition path requires a Session id.");
-  return `/app/sessions/${encodeURIComponent(normalized)}/chat`;
+  return buildNormalizedSessionChatPath(sessionId);
 }
 
 export function shouldBlockSessionHistoryTransition({
   committedSessionId,
   nextPathname,
+  currentPathname = cleanSessionChatPath(committedSessionId),
+  currentSearch = "",
+  nextSearch = "",
 }) {
-  const nextSessionId = sessionIdFromCleanChatPath(nextPathname);
-  return Boolean(nextSessionId && nextSessionId !== committedSessionId);
+  const outcome = classifySessionChatNavigationFromUrls({
+    committedSessionId,
+    currentUrl: `${currentPathname}${currentSearch}`,
+    targetUrl: `${nextPathname}${nextSearch}`,
+    source: "browser_history",
+    historyPolicy: "pop",
+  });
+  return outcome === SESSION_CHAT_NAVIGATION_OUTCOMES.CROSS_SESSION_TRANSITION;
 }
 
 export function sessionTransitionVerificationDelayMs({ hostname, search }) {

package/dev/client/connectivity/test-completed-message-neighbor-click.mjs

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { createCompletedMessageNeighborClickCoordinator } from "./completed-message-neighbor-click.mjs";
+
+const response = (previous, next) => ({ previous, next });
+const selectTarget = (value, direction) => value[direction]?.event_id;
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+test("mount, refresh, anchor and 100 local focus/scroll changes do not read", async () => {
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async () => {
+      reads += 1;
+      return response(null, { event_id: "$next" });
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  for (const signal of ["mount", "anchor-change", "session-data-refresh-after-five-seconds"]) {
+    assert.ok(signal);
+    assert.equal(coordinator.isLoading(), false);
+  }
+  for (let index = 0; index < 100; index += 1) {
+    // These represent timeline-local anchor/focus/scroll changes. The
+    // coordinator intentionally exposes no background-read operation.
+    assert.equal(coordinator.isLoading(), false);
+  }
+  assert.equal(reads, 0);
+
+  const result = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.equal(result.status, "target");
+  assert.equal(result.targetEventId, "$next");
+  assert.equal(reads, 1);
+});
+
+test("each direction uses exactly one request and preserves click-time anchor", async () => {
+  const requests = [];
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async (request) => {
+      requests.push(request);
+      return response({ event_id: "$previous" }, { event_id: "$next" });
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const previous = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "previous",
+    anchorEventId: "$visible-anchor",
+  });
+  const next = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.deepEqual(
+    [previous.status, previous.targetEventId, next.status, next.targetEventId],
+    ["target", "$previous", "target", "$next"]
+  );
+  assert.deepEqual(requests, [
+    {
+      roomId: "room",
+      anchorEventId: "$visible-anchor",
+      anchorPosition: undefined,
+    },
+    { roomId: "room", anchorEventId: undefined, anchorPosition: "latest" },
+  ]);
+});
+
+test("double click is rejected while the first transaction owns its response", async () => {
+  const pending = deferred();
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: () => {
+      reads += 1;
+      return pending.promise;
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const first = coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  const second = await coordinator.click({
+    scope: "session:room",
+    roomId: "room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  assert.equal(second.status, "busy");
+  assert.equal(reads, 1);
+  pending.resolve(response(null, { event_id: "$fixed" }));
+  assert.equal((await first).targetEventId, "$fixed");
+});
+
+test("no-result and error release the next click", async () => {
+  const replies = [
+    response(null, null),
+    new Error("offline"),
+    response(null, { event_id: "$new" }),
+  ];
+  let reads = 0;
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: async () => {
+      const reply = replies[reads++];
+      if (reply instanceof Error) throw reply;
+      return reply;
+    },
+    selectTarget,
+  });
+  coordinator.setScope("session:room");
+  const click = () =>
+    coordinator.click({
+      scope: "session:room",
+      roomId: "room",
+      direction: "next",
+      anchorPosition: "latest",
+    });
+  assert.equal((await click()).status, "no_target");
+  assert.equal((await click()).status, "error");
+  const recovered = await click();
+  assert.equal(recovered.status, "target");
+  assert.equal(recovered.targetEventId, "$new");
+  assert.equal(reads, 3);
+});
+
+test("scope change rejects a late response and never substitutes a new target", async () => {
+  const pending = deferred();
+  const coordinator = createCompletedMessageNeighborClickCoordinator({
+    readNeighbors: () => pending.promise,
+    selectTarget,
+  });
+  coordinator.setScope("old-session:old-room");
+  const oldClick = coordinator.click({
+    scope: "old-session:old-room",
+    roomId: "old-room",
+    direction: "next",
+    anchorPosition: "latest",
+  });
+  coordinator.setScope("new-session:new-room");
+  pending.resolve(response(null, { event_id: "$old-target" }));
+  assert.equal((await oldClick).status, "stale");
+});
+
+test("RoomTimeline keeps the established focus and cold-load paths", () => {
+  const clientRoot = join(import.meta.dirname, "..");
+  const source = readFileSync(
+    join(clientRoot, "web-chat/src/app/features/room/RoomTimeline.tsx"),
+    "utf8"
+  );
+  assert.match(source, /requestOysterunActiveRoomTimelineFocus\(\{/);
+  assert.match(source, /void handleOpenEvent\(targetEventId\)/);
+  assert.match(source, /loadEventTimeline\(evtId\)/);
+  assert.match(source, /getOysterunHostSessionChatFocusPath\(targetEventId\)/);
+  assert.doesNotMatch(source, /debouncedRequestRouteCHostOwnerNeighbors/);
+  assert.doesNotMatch(source, /routeCHostOwnerNeighborPendingRequestRef/);
+  assert.doesNotMatch(source, /routeCHostOwnerNeighborInvalidationSeq/);
+});