prts-terrarchive 0.2.0

package/ui/rhine/temporary-render-diagnostics.ts

@@ -0,0 +1,105 @@
+// TEMPORARY RHINE PROFILER: hooks exist only while a capture is running.
+import type { WebGLRenderer } from 'three';
+import type { FrameToken } from './temporary-performance';
+export type DiagnosticPass = { name: string; pass: { render: (...args: any[]) => any } };
+
+/** Source payload accounting only. Never inspect or retain pixels, text or handles. */
+export function uploadSize(method: string, args: any[]) {
+  let source: any, allocationBytes = 0;
+  if (method === 'bufferData') {
+    if (typeof args[1] === 'number') allocationBytes = args[1]; else source = args[1];
+  } else if (method === 'bufferSubData') source = args[2];
+  else if (method === 'texImage2D') source = args.length >= 9 ? args[8] : args[5];
+  else if (method === 'texSubImage2D') source = args.length >= 9 ? args[8] : args[6];
+  else if (method === 'texImage3D') source = args[9];
+  else if (method === 'texSubImage3D') source = args[10];
+  else if (method.startsWith('compressedTex')) source = args.slice().reverse().find(a => ArrayBuffer.isView(a));
+  let sourceBytes = source instanceof ArrayBuffer || ArrayBuffer.isView(source) ? source.byteLength : 0;
+  if (sourceBytes && method.startsWith('buffer') && ArrayBuffer.isView(source)) {
+    const unit = (source as { BYTES_PER_ELEMENT?: number }).BYTES_PER_ELEMENT || 1;
+    const offset = Number(args[3]) || 0, length = Number(args[4]) || 0;
+    sourceBytes = Math.min(Math.max(0, sourceBytes - offset * unit), length > 0 ? length * unit : Infinity);
+  }
+  const sourcePixels = source && !sourceBytes && typeof source !== 'number'
+    && Number.isFinite(source.width) && Number.isFinite(source.height) ? source.width * source.height : 0;
+  return { sourceBytes, sourcePixels, allocationBytes };
+}
+const surfaceName = /^(?:Case_Engraving|Printed_Label|Frosted_Polymer|Ivory_Edges|Optical_|Subsurface_|Amber_|Champagne_|Moulded_|Titanium_|Index_|Internal_|Array_Interior|Shelf_Interior|Rhine_Archive_Label)[A-Za-z0-9_]*$/;
+
+export function installRenderDiagnostics(renderer: WebGLRenderer, frame: () => FrameToken | undefined,
+  stage: (name: string) => void, passes: DiagnosticPass[], now: () => number,
+  outside: (detail: Record<string, unknown>) => void) {
+  const restore: (() => void)[] = [];
+  const replace = (owner: any, key: string, make: (original: (...args: any[]) => any) => (...args: any[]) => any) => {
+    const original = owner[key]; if (typeof original !== 'function') return;
+    const own = Object.getOwnPropertyDescriptor(owner, key), wrapper = make(original);
+    owner[key] = wrapper;
+    restore.push(() => { if (owner[key] !== wrapper) return; if (own) Object.defineProperty(owner, key, own); else delete owner[key]; });
+  };
+  for (const { name, pass } of passes) replace(pass, 'render', original => function(this: unknown, ...args: any[]) {
+    const token = frame(); if (!token?.detailed) return original.apply(this, args);
+    stage(name);
+    const start = now(), beforeCalls = renderer.info.render.calls, beforeTriangles = renderer.info.render.triangles;
+    try { return original.apply(this, args); }
+    finally {
+      const end = now(), row = token.sample.passWork![name] ||= { cpuMs: 0, calls: 0, triangles: 0 };
+      row.cpuMs += end - start; row.calls += renderer.info.render.calls - beforeCalls;
+      row.triangles += renderer.info.render.triangles - beforeTriangles;
+      token.sample.detailProbeMs! += now() - end;
+    }
+  });
+  let lastToken: FrameToken | undefined;
+  let rows = new Map<string, NonNullable<FrameToken['sample']['drawFamilies']>[number]>();
+  replace(renderer, 'renderBufferDirect', original => function(this: unknown, camera: any, scene: any, geometry: any, material: any, object: any, group: any) {
+    const token = frame(); if (!token?.detailed) return original.call(this, camera, scene, geometry, material, object, group);
+    const beforeCalls = renderer.info.render.calls, beforeTriangles = renderer.info.render.triangles;
+    try { return original.call(this, camera, scene, geometry, material, object, group); }
+    finally {
+      const start = now();
+      if (lastToken !== token) { rows = new Map(); lastToken = token; }
+      let ancestor = object, family = 'other';
+      if (family === 'other') while (ancestor) {
+        const tag = ancestor.userData?.performanceFamily;
+        if (['hero', 'shelf', 'moving', 'rack', 'board', 'array'].includes(tag)) { family = tag; break; }
+        ancestor = ancestor.parent;
+      }
+      if (family === 'other' && object?.isInstancedMesh) family = 'array';
+      const candidate = object?.userData?.surface || object?.name || '';
+      const part = typeof candidate === 'string' && candidate.length < 100 && surfaceName.test(candidate) ? candidate : 'other';
+      const phase = material?.isMeshDepthMaterial || material?.isMeshDistanceMaterial ? 'shadow' : token.gpuStage || 'unknown';
+      const materialKind = material?.isMeshPhysicalMaterial ? 'physical' : material?.isMeshStandardMaterial ? 'standard'
+        : material?.isMeshBasicMaterial ? 'basic' : material?.isShaderMaterial ? 'shader' : 'other';
+      const key = [family, part, phase, materialKind].join(':');
+      let row = rows.get(key);
+      if (!row && rows.size < 96) {
+        row = { family, part, material: materialKind, phase, calls: 0, triangles: 0 };
+        rows.set(key, row); token.sample.drawFamilies!.push(row);
+      }
+      if (row) { row.calls += renderer.info.render.calls - beforeCalls; row.triangles += renderer.info.render.triangles - beforeTriangles; }
+      else token.sample.counters.detailDrawGroupsDropped = (Number(token.sample.counters.detailDrawGroupsDropped) || 0) + 1;
+      token.sample.detailProbeMs! += now() - start;
+    }
+  });
+  const gl = renderer.getContext();
+  for (const method of ['texImage2D', 'texSubImage2D', 'texImage3D', 'texSubImage3D', 'compressedTexImage2D',
+    'compressedTexSubImage2D', 'generateMipmap', 'bufferData', 'bufferSubData']) {
+    replace(gl, method, original => function(this: unknown, ...args: any[]) {
+      const token = frame();
+      if (method.startsWith('buffer') && !token?.detailed) return original.apply(this, args);
+      const start = now();
+      try { return original.apply(this, args); }
+      finally {
+        const end = now(), sizes = uploadSize(method, args);
+        if (token) {
+          token.sample.glWork ||= {};
+          const key = (token.gpuStage || 'whole-frame') + ':' + method;
+          const row = token.sample.glWork[key] ||= { calls: 0, cpuMs: 0, sourceBytes: 0, sourcePixels: 0, allocationBytes: 0 };
+          row.calls++; row.cpuMs += end - start;
+          row.sourceBytes += sizes.sourceBytes; row.sourcePixels += sizes.sourcePixels; row.allocationBytes += sizes.allocationBytes;
+          token.sample.detailProbeMs = (token.sample.detailProbeMs || 0) + now() - end;
+        } else outside({ kind: 'gl-upload-outside-frame', method, cpuMs: end - start, ...sizes });
+      }
+    });
+  }
+  return () => { for (const fn of restore.reverse()) fn(); rows.clear(); lastToken = undefined; };
+}

package/ui/rhine/tool-activity.ts

@@ -0,0 +1,69 @@
+import type { ArchiveOperation, ArchiveSource, InvestigationSnapshot, InvestigationToolCall } from './types';
+
+/** Tool receipts drive the HUD; an earlier assistant paragraph is not completion. */
+export function investigationActivity(snapshot: InvestigationSnapshot) {
+  const calls: InvestigationToolCall[] = snapshot.toolCalls ?? snapshot.operations ?? [];
+  const active = snapshot.running ? calls.filter(call => call.state === 'active'
+    && !calls.some(child => child.state === 'active' && child.id.startsWith(`${call.id}:`))) : [];
+  const current = active.at(-1);
+  const latest = calls.at(-1);
+  return {
+    calls, active, current, recent: calls.slice(-3),
+    label: current ? `正在调用 ${current.tool}` : snapshot.running ? '等待下一步'
+      : snapshot.outcome === 'completed' ? '本轮调查已完成'
+      : snapshot.outcome === 'interrupted' ? '调查已停止' : snapshot.error ? '调查未完成'
+      : snapshot.answer ? '已返回内容' : '等待开始调查',
+    detail: current ? [current.query, active.length > 1 ? `另有 ${active.length - 1} 个调用进行中` : ''].filter(Boolean).join(' · ')
+      : snapshot.running ? latest ? `${latest.tool} ${latest.state === 'error' ? '调用失败' : '已返回'} · 等待 Agent 继续`
+        : '等待首次工具调用' : snapshot.error || '',
+    showReport: Boolean(snapshot.answer) && !snapshot.running && !active.length,
+  };
+}
+
+function webUrl(value?: string) {
+  try { const url = new URL(value || ''); if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return ''; url.hash = ''; return url.href; } catch { return ''; }
+}
+
+export function operationSource(operation: ArchiveOperation, sources: ArchiveSource[]) {
+  const candidates = sources.filter(source => !operation.dataVersion || source.dataVersion === operation.dataVersion);
+  const returned = candidates.find(source => operation.sourceIds.includes(source.id));
+  if (returned) return returned;
+  if (operation.tool === 'web_fetch' && operation.url) {
+    const url = webUrl(operation.url);
+    if (!url) return undefined;
+    const source = candidates.find(item => item.id === `web:${url}` || item.origin === 'web' && webUrl(item.url) === url);
+    if (source) return source;
+    // A live URL is a reading target, not a returned source: keep this card out
+    // of the material rack and counters until an actual receipt arrives.
+    if (operation.state !== 'complete') return { id: `web:${url}`, url, title: url, kind: 'web_page',
+      origin: 'web' as const, state: 'found' as const, excerpt: operation.state === 'active' ? '正在获取网页内容，返回后可阅读。' : '网页读取未完成。' };
+    return undefined;
+  }
+  const matches = candidates.filter(source => operation.documentUid ? source.documentUid === operation.documentUid
+    : operation.documentId ? source.documentId === operation.documentId
+    : Boolean(operation.sourceRef && source.sourceRef === operation.sourceRef));
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+/** One card per real read call, including a repeat read of the same document. */
+export function latestReadFocus(snapshot: InvestigationSnapshot, sources: ArchiveSource[]) {
+  const reads = (snapshot.operations || []).filter(call => call.kind === 'read');
+  const operation = reads.at(-1);
+  if (!operation) return undefined;
+  const source = operationSource(operation, sources);
+  if (!source) return undefined;
+  return { key: `${snapshot.sessionId}:${snapshot.investigationId || ''}:${operation.id}`, source, operation };
+}
+
+/** New calls move the whole card downward once; streamed snapshots stay still. */
+export class ReadCardMotion {
+  private animation?: Animation;
+  reveal(element: HTMLElement, reduced: boolean) {
+    this.dispose();
+    if (!reduced) this.animation = element.animate([
+      { opacity: 0, transform: 'translateY(-20px)' },
+      { opacity: 1, transform: 'translateY(0)' },
+    ], { duration: 340, easing: 'cubic-bezier(.22,1,.36,1)' });
+  }
+  dispose() { this.animation?.cancel(); this.animation = undefined; }
+}

package/ui/rhine/types.ts

@@ -0,0 +1,219 @@
+import type { RenderQuality } from './original/render-quality';
+import type { EvidenceCard, EvidenceBoardTool, EvidenceTemplate } from './evidence-board-model';
+
+export interface BoardAnchorPoint { x: number; y: number; visible: boolean }
+export interface BoardAnchorFrame {
+  corner: BoardAnchorPoint;
+  chalk: BoardAnchorPoint;
+  /** Clockwise corners of the view label on the board plane, in stage pixels. */
+  controls: [BoardAnchorPoint, BoardAnchorPoint, BoardAnchorPoint, BoardAnchorPoint];
+  /** Board-local writing surface, clockwise. Offscreen corners remain valid projection anchors. */
+  surface: [BoardAnchorPoint, BoardAnchorPoint, BoardAnchorPoint, BoardAnchorPoint];
+  width: number;
+  height: number;
+  zoom: number;
+  visible: boolean;
+}
+
+export type RhineLocation = 'board' | 'archive' | 'desk';
+
+export type ArchiveOrigin = 'local' | 'cloud' | 'web';
+export type ArchiveState = 'found' | 'read' | 'cited';
+export interface ArchiveSource {
+  id: string;
+  title: string;
+  kind: string;
+  origin: ArchiveOrigin;
+  state: ArchiveState;
+  agentRead?: boolean;
+  excerpt: string;
+  /** The exact web_fetch text received by the Agent, separate from the preview excerpt. */
+  content?: string;
+  contentTruncated?: boolean;
+  documentId?: string;
+  documentUid?: string;
+  sourceRef?: string;
+  dataVersion?: string;
+  lineStart?: number;
+  lineEnd?: number;
+  url?: string;
+  callId?: string;
+  ranges?: { start: number; end: number }[];
+  readRanges?: { start: number; end: number }[];
+  /** Position explicitly requested by a clue/report citation, not an Agent read receipt. */
+  readingRange?: { start: number; end: number };
+  saved?: boolean;
+}
+/** One actual tool invocation, retained after completion for visual playback. */
+export interface ArchiveOperation {
+  id: string;
+  tool: string;
+  kind: 'search' | 'read';
+  state: 'active' | 'complete' | 'error';
+  /** Final merged source IDs delivered by this invocation; reads exclude unread pointers. */
+  sourceIds: string[];
+  /** Requested HTTP(S) page, available before a web_fetch result exists. */
+  url?: string;
+  documentId?: string;
+  documentUid?: string;
+  sourceRef?: string;
+  dataVersion?: string;
+  query?: string;
+  /** Actual Host event times, absent when the loaded history lacks that boundary. */
+  startedAt?: number;
+  completedAt?: number;
+}
+export interface InvestigationToolCall {
+  id: string;
+  tool: string;
+  state: 'active' | 'complete' | 'error';
+  query?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+export interface InvestigationSnapshot {
+  sessionId: string;
+  running: boolean;
+  searching: boolean;
+  query: string;
+  tool: string;
+  sources: ArchiveSource[];
+  answer: string;
+  /** Stable identity of the current durable turn, or its pending user message. */
+  investigationId?: string;
+  /** Only a durable successful turn/end confirms completed. */
+  outcome?: 'running' | 'completed' | 'interrupted' | 'error' | 'unknown';
+  /** Sources received in this turn; the main sources array remains cumulative. */
+  turnSources?: ArchiveSource[];
+  /** Sources explicitly cited by the current answer, including reused older sources. */
+  reportSources?: ArchiveSource[];
+  /** Host event time for a confirmed successful turn/end. */
+  completedAt?: number;
+  question?: string;
+  phase?: 'idle' | 'searching' | 'reading' | 'synthesizing' | 'complete' | 'error';
+  activeDocumentId?: string;
+  activeSourceRef?: string;
+  activeDataVersion?: string;
+  error?: string;
+  hasMoreHistory?: boolean;
+  loadingHistory?: boolean;
+  records?: { id: string; tool: string; state: 'active' | 'complete' | 'error'; query: string; text: string }[];
+  /** Current-turn tool activities; parallel and already completed calls remain distinct. */
+  operations?: ArchiveOperation[];
+  /** All current-turn Host tools, including nested and non-corpus calls. */
+  toolCalls?: InvestigationToolCall[];
+}
+export interface RhineScene {
+  /** Resolves after queued scene preparation and a complete rendered frame. */
+  whenReady(): Promise<void>;
+  setLocation(location: RhineLocation): void;
+  setBoardFullscreen(fullscreen: boolean): void;
+  setBoardEditorInset(bottomFraction: number): void;
+  cancelBoardGesture(): boolean;
+  resetBoardView(): void;
+  zoomBoard(direction: -1 | 1): void;
+  setBoardTool(tool: EvidenceBoardTool): void;
+  setEvidenceInbox(value:import('./evidence-inbox').EvidenceInboxView,open:boolean):void;
+  getBoardCardBounds(id: string): { left: number; right: number; top: number; bottom: number } | null;
+  setBoardCards(cards: EvidenceCard[]): void;
+  selectBoardCard(id: string | null): void;
+  setSearching(searching: boolean): void;
+  setFollowAgent(value: boolean): void;
+  setSources(sources: ArchiveSource[], animate?: boolean): void;
+  setArchiveSources(sources: ArchiveSource[]): void;
+  selectArchiveSource(id: string, userInitiated?: boolean): void;
+  browseArchiveSource(id: string): boolean;
+  setInvestigation(snapshot: InvestigationSnapshot): void;
+  setShelfPage(page: number): void;
+  browseShelf(direction: number): void;
+  select(id: string | null): void;
+  navigate(axis: 'row' | 'lane', direction: number): boolean;
+  selectArchive(index: number): void;
+  setDetail(open: boolean): void;
+  setReadingObject(value: import('./reading-object').ReadingObject | null): void;
+  createAssemblyModel(): Promise<{ model: import('three').Group; dispose: () => void; setClarity?: (value: number) => void }>;
+  finishDecryption(): void;
+  setActive(active: boolean): void;
+  setReducedMotion(reduced: boolean): void;
+  setQuality(quality: RenderQuality): void;
+  resize(): void;
+  stats(): Record<string, unknown>;
+  dispose(): void;
+}
+export interface RhineSceneOptions {
+  assetBase: string;
+  navigationLimiter?: import('./archive-navigation-limit').ArchiveNavigationLimiter;
+  /** TEMPORARY RHINE PROFILER */
+  performanceProbe?: import('./temporary-performance').RenderPerformanceCapture;
+  /** Opening boundary used to distinguish late history from live tool receipts. */
+  activitySince?: number;
+  reducedMotion?: boolean;
+  onSelect?: (id: string) => void;
+  onArchiveSelect?: (index: number) => void;
+  onArchiveOpen?: (index: number) => void;
+  onArchiveSourceSelect?: (id: string | null, lane: number, userInitiated?: boolean) => void;
+  onArchiveSourceOpen?: (id: string) => void;
+  onShelfSelect?: (id: string | null, page: number) => void;
+  onLocationRequest?: (location: RhineLocation) => void;
+  onInboxOpen?:()=>void;
+  onInboxAnchor?: (value:import('./evidence-inbox').EvidenceInboxAnchor)=>void;
+  onBoardSelect?: (id: string | null, openEditor?: boolean) => void;
+  onBoardMove?: (id: string, x: number, y: number) => void;
+  onBoardResize?: (id: string, scale: number, x: number, y: number) => void;
+  onBoardAnchors?: (frame: BoardAnchorFrame) => void;
+  onBoardToolRequest?: () => void;
+  onBoardToolChange?: (tool: EvidenceBoardTool) => void;
+  onBoardPlace?: (template: EvidenceTemplate, position: { x: number; y: number }) => void;
+  onBoardConnect?: (fromId: string, toId: string) => void;
+  onDetailFrame?: (visibility: number) => void;
+  onError?: (message: string) => void;
+}
+export interface RhineOptions {
+  assetBase: string;
+  snapshot: InvestigationSnapshot;
+  agentAvailable?: boolean;
+  api: (endpoint: string, payload?: unknown, signal?: AbortSignal) => Promise<any>;
+  askAgent: (text: string) => Promise<void>;
+  loadHistory?: () => Promise<void>;
+  host?: RhineHostControls;
+  /** Per-controller upstream snapshot diagnostics, without snapshot contents. */
+  snapshotDiagnostics?: Pick<RhineHostControls, 'setPerformanceMonitor' | 'performanceStats'>;
+  close: () => void;
+  openSettings?: () => boolean;
+  isSettingsOpen?: () => boolean;
+}
+export interface RhineHostState {
+  sessionId: string;
+  title: string;
+  workspace: string;
+  blank: boolean;
+  running: boolean;
+  busy: boolean;
+  loading: boolean;
+  canSubmit: boolean;
+  error: string;
+  mode: string;
+  modes: { id: string; name: string; description: string }[];
+  sessions: { id: string; title: string; workspace: string; running: boolean; updatedAt: number }[];
+  model: string;
+  models: { id: string; name: string }[];
+}
+export interface RhineHostControls {
+  /** Optional bounded diagnostics for the host-to-workbench notification bridge. */
+  setPerformanceMonitor?(monitor?: (kind: string) => (() => void) | undefined): void;
+  performanceStats?(): Record<string, unknown>;
+  getState(): RhineHostState;
+  subscribe(listener: (state: RhineHostState) => void): () => void;
+  refresh(): Promise<void>;
+  createSession(mode?: string): Promise<void>;
+  openSession(id: string): Promise<void>;
+  selectMode(id: string): Promise<void>;
+  selectModel(id: string): Promise<void>;
+  cancel(): Promise<void>;
+}
+export interface RhineWorkbench {
+  update(snapshot: InvestigationSnapshot): void;
+  setActive(active: boolean): void;
+  dispose(): void;
+  stats(): Record<string, unknown>;
+}

package/ui/rhine/visible-scene-hit.ts

@@ -0,0 +1,13 @@
+import type * as THREE from 'three';
+
+/** Raycaster visits hidden descendants too; navigation must respect what is actually shown. */
+export function visibleSceneHit(hits: THREE.Intersection[]): THREE.Intersection | undefined {
+  return hits.find(hit => {
+    for (let object: THREE.Object3D | null = hit.object; object; object = object.parent) {
+      if (!object.visible) return false;
+    }
+    const material = (hit.object as THREE.Mesh).material;
+    const materials = Array.isArray(material) ? material : [material];
+    return materials.some(value => !value || value.visible && value.opacity > 0);
+  });
+}