@tiinex/app 0.1.1

package/src/app/timePortalSnapshotResolution.js

@@ -0,0 +1,53 @@
+import { resolveGithubSnapshotInput } from '../adapters/github/github.repoDiscovery.js';
+import { normalizeResolvedSnapshot, timePortalIntentFor } from '../workspaces/workspace.timePortal.js';
+
+export function timePortalGithubSources(workspace = {}) {
+  return (Array.isArray(workspace?.sources) ? workspace.sources : [])
+    .filter((source) => source && source.id !== 'local' && (source.adapterId === 'github' || source.sourceKind === 'github.repo' || source.kind === 'github-tree'))
+    .map((source) => ({
+      id: String(source.id || '').trim(),
+      label: String(source.label || source.repo || 'GitHub source').trim(),
+      repository: String(source.repo || source.repository || source.config?.repo || '').trim(),
+      ref: String(source.ref || source.config?.ref || '').trim(),
+      rootPath: String(source.rootPath || source.config?.rootPath || '').trim()
+    }))
+    .filter((source) => source.id && source.repository);
+}
+
+export function selectedTimePortalGithubSource(workspace = {}, sourceId = '') {
+  const candidates = timePortalGithubSources(workspace);
+  const id = String(sourceId || '').trim();
+  if (id) return candidates.some((source) => source.id === id)
+    ? (workspace.sources || []).find((source) => source.id === id) || null
+    : null;
+  if (candidates.length !== 1) return null;
+  return (workspace.sources || []).find((source) => source.id === candidates[0].id) || null;
+}
+
+export async function resolveTimePortalSnapshot({ workspace, view = {}, sourceId = '', snapshotInput = '', fetchImpl } = {}) {
+  const candidates = timePortalGithubSources(workspace);
+  const selectedId = String(sourceId || timePortalIntentFor(view).sourceId || '').trim();
+  if (!selectedId && candidates.length > 1) return failure('time-portal.source.ambiguous', 'Choose which configured GitHub source to review historically.');
+  const source = selectedTimePortalGithubSource(workspace, selectedId);
+  if (!source) return failure(candidates.length ? 'time-portal.source.required' : 'time-portal.source.unsupported', candidates.length ? 'Choose a configured GitHub source.' : 'Time Portal requires a configured GitHub repository source.');
+  const input = String(snapshotInput || timePortalIntentFor(view).snapshotInput || '').trim();
+  if (!input) return failure('time-portal.snapshot-input.required', 'Paste an exact commit, GitHub commit/tree URL, or explicit ref.');
+  const resolved = await resolveGithubSnapshotInput(source, input, { fetchImpl });
+  if (!resolved.ok) return failure(resolved.code || 'time-portal.snapshot.resolve.failed', resolved.message || 'Snapshot resolution failed.', { transportStatus: resolved.status || null });
+  const snapshot = normalizeResolvedSnapshot({
+    sourceId: source.id,
+    repository: resolved.repository,
+    rootPath: source.rootPath || source.config?.rootPath || '',
+    requestedRef: resolved.requestedRef,
+    resolvedRef: resolved.resolvedRef,
+    materializedCommit: resolved.materializedCommit,
+    inputTarget: resolved.inputTarget,
+    resolvedBy: resolved.resolvedBy
+  });
+  if (!snapshot) return failure('time-portal.snapshot.identity.invalid', 'Snapshot did not resolve to an exact immutable source identity.');
+  return { ok: true, schema: 'tiinex.site.timePortalSnapshotResolution.v1', sourceId: source.id, snapshot };
+}
+
+function failure(code, message, extras = {}) {
+  return Object.assign({ ok: false, schema: 'tiinex.site.timePortalSnapshotResolution.v1', code, message }, extras);
+}

package/src/app/urlMaterialCommand.js

@@ -0,0 +1,24 @@
+import { materializeExplicitUrls } from '../adapters/static/static.adapter.js';
+
+export async function runExplicitUrlMaterialImportCommand(input = {}) {
+  const lifecycle = input.lifecycle;
+  const state = input.state;
+  const workspaceId = String(input.workspaceId || state?.activeWorkspaceId || '').trim();
+  const urls = Array.isArray(input.urls) ? input.urls.map((url) => String(url || '').trim()).filter(Boolean) : String(input.urlText || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (!urls.length) return { ok: false, error: 'url.required', state, notice: 'Paste at least one URL.' };
+  try {
+    const adapterResult = await materializeExplicitUrls(urls, { fetchImpl: input.fetchImpl });
+    if (!adapterResult.records.length) return { ok: false, error: 'url.material.empty', state, notice: `No URLs could be loaded${adapterResult.errors?.length ? '; check CORS/source availability.' : '.'}`, adapterResult };
+    const result = lifecycle?.addWorkspaceRecords?.(state, workspaceId, adapterResult.records);
+    if (!result?.ok) return { ok: false, error: result?.error || 'url.material.add.failed', state, notice: 'Could not add URL material.', adapterResult };
+    return {
+      ok: true,
+      state: result.state,
+      records: result.records || [],
+      adapterResult,
+      notice: `Added ${result.records.length} URL artifact${result.records.length === 1 ? '' : 's'}${adapterResult.errors?.length ? `; ${adapterResult.errors.length} failed` : ''}.`
+    };
+  } catch (exception) {
+    return { ok: false, error: 'url.material.exception', exception, state, notice: 'Could not load URL material.' };
+  }
+}

package/src/app/useCanonicalPlacementSelectionOptions.js

@@ -0,0 +1,9 @@
+import { useMemo } from 'react';
+import { workspacePlacementOptions } from './workspacePlacementOptions.js';
+
+export function useCanonicalPlacementSelectionOptions({ state, actionRecord = null, recordAction = null, actionWorkspace = null, dialog = '', dialogWorkspace = null } = {}) {
+  const authoringActive = Boolean(actionRecord && recordAction?.action?.kind === 'canonical-transition-product' && recordAction?.action?.referenceCapability?.state !== 'qualified');
+  const action = useMemo(() => authoringActive && actionWorkspace?.id ? workspacePlacementOptions(state, actionWorkspace.id) : null, [authoringActive, state, actionWorkspace?.id]);
+  const dialogOptions = useMemo(() => dialog === 'create-artifact' && dialogWorkspace?.id ? workspacePlacementOptions(state, dialogWorkspace.id) : null, [dialog, state, dialogWorkspace?.id]);
+  return Object.freeze({ action, dialog: dialogOptions });
+}

package/src/app/useCanonicalReferenceSelectionOptions.js

@@ -0,0 +1,8 @@
+import { useMemo } from 'react';
+import { canonicalReferenceTargetOptions } from './canonicalReferenceTargets.js';
+
+export function useCanonicalReferenceSelectionOptions({ state, actionRecord = null, recordAction = null, actionWorkspace = null } = {}) {
+  return useMemo(() => (actionRecord && recordAction?.action?.referenceCapability?.state === 'qualified'
+    ? canonicalReferenceTargetOptions({ state, subjectWorkspaceId: actionWorkspace?.id || '', subjectRecord: actionRecord, targetSchemaId: recordAction.action.referenceCapability.targetSchemaId })
+    : null), [state, actionRecord, actionWorkspace, recordAction]);
+}

package/src/app/useLocalMaterialIntake.js

@@ -0,0 +1,68 @@
+import { useState } from 'react';
+import { makePastedTraceFile, runLocalMaterialImportCommand } from './localMaterialCommand.js';
+
+export function useLocalMaterialIntake({ getLifecycle, getState, getPersistenceOwnership = null, workspaceId = '', setNotice, setDialog, commit, windowObj = null } = {}) {
+  const [pendingLocalImport, setPendingLocalImport] = useState(null);
+
+  async function addLocalFiles(fileList, options = {}, preparedAdapterResult = null) {
+    const targetWorkspaceId = String(options.workspaceId || workspaceId || '').trim();
+    const passwordProvider = options.passwordProvider || passwordProviderForWindow(windowObj);
+    const commandOptions = Object.assign({}, options, { passwordProvider });
+    const result = await runLocalMaterialImportCommand({
+      lifecycle: getLifecycle?.(),
+      state: getState?.(),
+      workspaceId: targetWorkspaceId,
+      fileList,
+      adapterResult: preparedAdapterResult,
+      options: commandOptions,
+      persistenceOwnership: getPersistenceOwnership?.() || null
+    });
+    if (result.exception) console.error(result.exception);
+    if (result.error === 'import.conflict.requires-resolution') {
+      setPendingLocalImport({ fileList: Array.from(fileList || []), adapterResult: result.adapterResult, options: Object.assign({}, commandOptions, { workspaceId: targetWorkspaceId }), conflicts: result.conflicts || [] });
+      setDialog?.('import-conflict');
+      setNotice?.('');
+      return false;
+    }
+    if (!result.ok) {
+      setNotice?.(result.notice || 'Could not add selected material.');
+      return false;
+    }
+    setPendingLocalImport(null);
+    setDialog?.(null);
+    setNotice?.(result.notice || 'Import completed.');
+    commit?.(result.state, 'push');
+    return true;
+  }
+
+  async function resolveLocalImportConflict(resolution) {
+    const pending = pendingLocalImport;
+    if (!pending) {
+      setDialog?.(null);
+      return false;
+    }
+    if (resolution === 'cancel') {
+      setPendingLocalImport(null);
+      setDialog?.('add-to-workspace');
+      return false;
+    }
+    return addLocalFiles(pending.fileList, Object.assign({}, pending.options, { conflictResolution: resolution }), pending.adapterResult);
+  }
+
+  function addPastedTrace(text) {
+    const file = makePastedTraceFile(text);
+    if (!file) {
+      setNotice?.('Clipboard text does not look like Tiinex trace Markdown.');
+      return false;
+    }
+    void addLocalFiles([file], { sourceMode: 'pasted-trace' });
+    return true;
+  }
+
+  return { addLocalFiles, resolveLocalImportConflict, addPastedTrace, pendingLocalImport };
+}
+
+export function passwordProviderForWindow(windowObj = null) {
+  if (!windowObj?.prompt) return undefined;
+  return async (file) => windowObj.prompt(`Password for ${file?.name || 'password-protected zip'}`) || '';
+}

package/src/app/useTimePortalProductController.jsx

@@ -0,0 +1,111 @@
+import { useState } from 'react';
+import { activeWorkspaceViewFor } from './workspaceMulticolumn.js';
+import { workspaceById } from './workspaceScopedInteraction.js';
+import { resolveTimePortalSnapshot } from './timePortalSnapshotResolution.js';
+import { historicalSnapshotReadModelKey, loadTimePortalHistoricalReadModel } from './timePortalHistoricalRead.js';
+import { timePortalViewFor, timePortalWithIntent, timePortalWithResolvedSnapshot, timePortalWithoutIntent } from '../workspaces/workspace.timePortal.js';
+
+export function useTimePortalProductController({
+  state,
+  latestStateRef,
+  activeWorkspaceId = '',
+  dialogWorkspaceId = '',
+  dialog = null,
+  commitWorkspaceViewUpdate,
+  setNotice,
+  setDialog,
+  setDialogWorkspaceId,
+  setActiveRecordId,
+  setActiveAssetId,
+  dismissDialog,
+  fetchImpl
+} = {}) {
+  const [historicalReads, setHistoricalReads] = useState({});
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+
+  const sourceState = () => latestStateRef?.current || state || {};
+  const targetIdFor = (workspaceId = '') => String(workspaceId || dialogWorkspaceId || sourceState().activeWorkspaceId || activeWorkspaceId || '').trim();
+
+  function readFor(workspace, view) {
+    const temporal = timePortalViewFor(view || {});
+    const key = temporal?.snapshot ? historicalSnapshotReadModelKey(temporal.snapshot) : '';
+    const candidate = key && workspace?.id ? historicalReads[workspace.id] : null;
+    return candidate?.key === key ? candidate : null;
+  }
+
+  function clearHistoricalRead(workspaceId = '') {
+    const targetId = targetIdFor(workspaceId);
+    if (!targetId) return;
+    setHistoricalReads((current) => { const next = Object.assign({}, current); delete next[targetId]; return next; });
+  }
+
+  function openResolver(intent = {}, workspaceId = '') {
+    const targetId = targetIdFor(workspaceId);
+    const currentView = activeWorkspaceViewFor(sourceState(), targetId);
+    const existing = timePortalViewFor(currentView);
+    commitWorkspaceViewUpdate?.(targetId, (view) => timePortalWithIntent(view, {
+      begin: intent.begin,
+      end: intent.end,
+      sourceId: existing?.sourceId || '',
+      snapshotInput: existing?.snapshotInput || ''
+    }), 'push');
+    setDialogWorkspaceId?.(targetId);
+    setError('');
+    setDialog?.('time-portal-resolve');
+  }
+
+  async function loadSnapshot(workspaceId = '', explicitSnapshot = null, explicitWorkspace = null) {
+    const targetId = targetIdFor(workspaceId);
+    const currentState = sourceState();
+    const workspace = explicitWorkspace || workspaceById(currentState, targetId);
+    const temporal = timePortalViewFor(activeWorkspaceViewFor(currentState, targetId));
+    const snapshot = explicitSnapshot || temporal?.snapshot || null;
+    if (!workspace || !snapshot) { setNotice?.('Resolve an exact source snapshot before historical loading.'); return null; }
+    setBusy(true);
+    const readModel = await loadTimePortalHistoricalReadModel({ workspace, snapshot, fetchImpl, options: { allowCache: true } });
+    setBusy(false);
+    setHistoricalReads((current) => Object.assign({}, current, { [targetId]: readModel }));
+    if (!readModel?.ok) setNotice?.(readModel?.message || 'Historical snapshot is unavailable. Latest source remains unchanged.');
+    else if (readModel.state === 'degraded') setNotice?.('Historical snapshot loaded with transport diagnostics. Latest source remains unchanged.');
+    return readModel;
+  }
+
+  async function resolveFromDialog({ sourceId = '', snapshotInput = '' } = {}) {
+    const currentState = sourceState();
+    const targetId = targetIdFor();
+    const workspace = workspaceById(currentState, targetId);
+    const currentView = activeWorkspaceViewFor(currentState, targetId);
+    setBusy(true); setError('');
+    const result = await resolveTimePortalSnapshot({ workspace, view: currentView, sourceId, snapshotInput, fetchImpl });
+    if (!result?.ok) { setBusy(false); setError(result?.message || 'Could not resolve source snapshot.'); return result; }
+    const currentIntent = Object.assign({}, timePortalViewFor(currentView) || {}, { sourceId: result.sourceId, snapshotInput });
+    const nextView = timePortalWithResolvedSnapshot(currentView, result.snapshot, currentIntent);
+    const safeView = Object.assign({}, nextView, ['feed', 'tree'].includes(nextView.workspaceVerse) ? {} : { workspaceVerse: 'feed' }, { selectedRecordId: '', lineageQuery: '', lineageAuditReport: null, lineageLoadReport: null });
+    commitWorkspaceViewUpdate?.(targetId, () => safeView, 'replace');
+    setDialog?.(null); setError('');
+    const readModel = await loadSnapshot(targetId, result.snapshot, workspace);
+    setBusy(false);
+    return Object.assign({}, result, { readModel });
+  }
+
+  function returnToLatest(workspaceId = '') {
+    const targetId = targetIdFor(workspaceId);
+    clearHistoricalRead(targetId);
+    setActiveRecordId?.(''); setActiveAssetId?.(''); setError('');
+    commitWorkspaceViewUpdate?.(targetId, (view) => timePortalWithoutIntent(view), 'push');
+    if (dialog === 'time-portal-resolve' || dialog === 'display-options') dismissDialog?.();
+  }
+
+  return {
+    historicalReads,
+    busy,
+    error,
+    readFor,
+    clearHistoricalRead,
+    openResolver,
+    loadSnapshot,
+    resolveFromDialog,
+    returnToLatest
+  };
+}

package/src/app/useWorkspaceEntrypointIntake.js

@@ -0,0 +1,77 @@
+import { useState } from 'react';
+import { runWorkspaceEntrypointIntakeCommand } from './workspaceEntrypointIntakeCommand.js';
+import { passwordProviderForWindow } from './useLocalMaterialIntake.js';
+
+export function useWorkspaceEntrypointIntake({
+  getLifecycle,
+  getState,
+  parseWorkspaceConfig,
+  setNotice,
+  setDialog,
+  commit,
+  getPersistenceOwnership = null,
+  materializeSource,
+  windowObj = null
+} = {}) {
+  const [pendingWorkspaceEntrypoint, setPendingWorkspaceEntrypoint] = useState(null);
+
+  async function handleGlobalWorkspaceDrop(fileList, options = {}) {
+    const result = await runWorkspaceEntrypointIntakeCommand({
+      lifecycle: getLifecycle?.(),
+      state: getState?.(),
+      parseWorkspaceConfig,
+      fileList,
+      options: Object.assign({}, options, { passwordProvider: options.passwordProvider || passwordProviderForWindow(windowObj) }),
+      persistenceOwnership: getPersistenceOwnership?.() || null
+    });
+    if (result.requiresChoice) {
+      setPendingWorkspaceEntrypoint({ adapterResult: result.adapterResult, workspaceEntries: result.workspaceEntries || [], options });
+      setDialog?.('workspace-entrypoint-choice');
+      setNotice?.('');
+      return false;
+    }
+    return finalizeWorkspaceEntrypointResult(result);
+  }
+
+  async function resolveWorkspaceEntrypointChoice(mode = '') {
+    const pending = pendingWorkspaceEntrypoint;
+    if (!pending) {
+      setDialog?.(null);
+      return false;
+    }
+    if (mode === 'cancel') {
+      setPendingWorkspaceEntrypoint(null);
+      setDialog?.(null);
+      return false;
+    }
+    const result = await runWorkspaceEntrypointIntakeCommand({
+      lifecycle: getLifecycle?.(),
+      state: getState?.(),
+      parseWorkspaceConfig,
+      adapterResult: pending.adapterResult,
+      mode,
+      options: pending.options || {},
+      persistenceOwnership: getPersistenceOwnership?.() || null
+    });
+    return finalizeWorkspaceEntrypointResult(result);
+  }
+
+  async function finalizeWorkspaceEntrypointResult(result = {}) {
+    if (!result?.ok) {
+      setNotice?.(result.notice || result.message || 'Could not apply workspace entrypoint.');
+      return false;
+    }
+    setPendingWorkspaceEntrypoint(null);
+    setDialog?.(null);
+    setNotice?.(result.notice || 'Workspace entrypoint applied.');
+    commit?.(result.state, 'push');
+    let materialState = result.state;
+    for (const sourceInput of result.sourceInputs || []) {
+      const loaded = await materializeSource?.(sourceInput, { state: materialState, workspaceId: sourceInput.workspaceId || '' });
+      if (loaded?.state) materialState = loaded.state;
+    }
+    return true;
+  }
+
+  return { handleGlobalWorkspaceDrop, resolveWorkspaceEntrypointChoice, pendingWorkspaceEntrypoint };
+}

package/src/app/useWorkspaceSelectionProductController.jsx

@@ -0,0 +1,21 @@
+import { useState } from 'react';
+import { createWorkspaceSelectionSession, workspaceSelectionResult } from './workspaceSelectionSession.js';
+
+export function useWorkspaceSelectionProductController({ setNotice = () => {}, captureOriginContext = null, restoreOriginContext = null } = {}) {
+  const [session, setSession] = useState(null);
+  const [result, setResult] = useState(null);
+  function begin(input = {}) {
+    const created = createWorkspaceSelectionSession({ ...input, originContext: input.originContext ?? captureOriginContext?.(input) ?? null });
+    if (!created.ok) { setNotice('Workspace selection could not start.'); return created; }
+    setResult(null); setSession(created); setNotice(created.title); return created;
+  }
+  function choose(candidate = {}) {
+    const selected = workspaceSelectionResult(session, candidate);
+    if (!selected.ok) { setNotice('That candidate is not qualified for this selection.'); return selected; }
+    const completed = session; setSession(null); restoreOriginContext?.(completed?.originContext, { reason: 'choose', session: completed, result: selected }); setResult(selected); setNotice('Selection applied to the pending draft.'); return selected;
+  }
+  function cancel() { const completed = session; setSession(null); restoreOriginContext?.(completed?.originContext, { reason: 'cancel', session: completed }); setNotice('Selection cancelled; draft preserved.'); }
+  function consume(sessionId = '') { setResult((current) => current?.sessionId === sessionId ? null : current); }
+  function reset() { const completed = session; setSession(null); setResult(null); if (completed) restoreOriginContext?.(completed.originContext, { reason: 'reset', session: completed }); }
+  return Object.freeze({ session, result, begin, choose, cancel, consume, reset });
+}

package/src/app/viewState.js

@@ -0,0 +1,35 @@
+export function workspaceViewScrollKeyFor(sourceState = {}, viewOverride = null, explicitWorkspaceId = '') {
+  const view = viewOverride || sourceState?.view || {};
+  const workspaceId = explicitWorkspaceId || sourceState?.activeWorkspaceId || 'workspace';
+  const verse = view.workspaceVerse || 'feed';
+  const query = verse === 'lineage' ? (view.lineageQuery || '') : (view.query || '');
+  const selected = verse === 'lineage' ? (view.selectedRecordId || '') : '';
+  const display = view.displayOptions ? JSON.stringify(view.displayOptions) : '';
+  return `${workspaceId}:${verse}:${query}:${selected}:${display}`;
+}
+
+export function stateWithViewPatch(sourceState = {}, patch = {}) {
+  return Object.assign({}, sourceState, {
+    view: Object.assign({}, sourceState.view || {}, patch)
+  });
+}
+
+export function stateWithViewUpdate(sourceState = {}, updater = null) {
+  const currentView = sourceState.view || {};
+  const nextView = typeof updater === 'function' ? updater(currentView, sourceState) : Object.assign({}, currentView, updater || {});
+  if (nextView === currentView) return sourceState;
+  return Object.assign({}, sourceState, { view: nextView });
+}
+
+export function stateWithCapturedViewScroll(nextState = {}, sourceState = {}, capturedScroll = {}, explicitWorkspaceId = '') {
+  const key = workspaceViewScrollKeyFor(sourceState, null, explicitWorkspaceId);
+  const top = capturedScroll?.[key];
+  if (!Number.isFinite(Number(top))) return nextState;
+  const scrollPositions = Object.assign({}, nextState.view?.scrollPositions || {});
+  const roundedTop = Math.max(0, Math.round(Number(top)));
+  if (Number(scrollPositions[key] || 0) === roundedTop) return nextState;
+  scrollPositions[key] = roundedTop;
+  return Object.assign({}, nextState, {
+    view: Object.assign({}, nextState.view || {}, { scrollPositions })
+  });
+}

package/src/app/viewport.js

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+
+export { shouldPageWorkspaces } from './workspaceWindow.js';
+
+export function useViewportWidth() {
+  const readWidth = () => {
+    if (typeof window === 'undefined') return 0;
+    return Math.floor(window.visualViewport?.width || window.innerWidth || 0);
+  };
+  const [width, setWidth] = useState(readWidth);
+  useEffect(() => {
+    const update = () => setWidth(readWidth());
+    window.addEventListener('resize', update);
+    window.visualViewport?.addEventListener?.('resize', update);
+    return () => {
+      window.removeEventListener('resize', update);
+      window.visualViewport?.removeEventListener?.('resize', update);
+    };
+  }, []);
+  return width;
+}