@tiinex/app 0.1.1

package/src/app/shareProjection.js

@@ -0,0 +1,190 @@
+import {
+  artifactPublicTargetFromRecord,
+  buildPublicViewerTargetUrl,
+  publicTargetFromRecord,
+  publicTargetFromWorkspace,
+  publicTargetRestoreCapability,
+  PublicTargetRestoreCapability
+} from './publicTarget.js';
+import { workspaceHasDurableLocalMaterial } from '../workspaces/workspace.openSemantics.js';
+
+export const SHARE_PROJECTION_SCHEMA = 'tiinex.shareProjection.v1';
+
+export const ShareScope = Object.freeze({
+  artifact: 'artifact',
+  workspace: 'workspace',
+  workspaceSet: 'workspace-set',
+  current: 'current'
+});
+
+export const ShareTargetStatus = Object.freeze({
+  available: 'available',
+  exactViewOnly: 'exact-view-only',
+  localOnly: 'local-only',
+  unavailable: 'unavailable'
+});
+
+export const ShareAccessStatus = Object.freeze({
+  unknown: 'unknown',
+  accessBound: 'access-bound',
+  notApplicable: 'not-applicable'
+});
+
+export function projectShareTruth({
+  scope = ShareScope.current,
+  state = {},
+  workspace = null,
+  record = null,
+  publicViewerUrl = '',
+  exactStateBaseUrl = '',
+  routeCodec = globalThis.TiinexWorkspaceRoute,
+  persistenceCodec = globalThis.TiinexWorkspacePersistence
+} = {}) {
+  const normalizedScope = normalizeScope(scope);
+  const exactStateUrl = normalizedScope === ShareScope.current
+    ? buildExactStateUrl(state, { baseUrl: exactStateBaseUrl, routeCodec, persistenceCodec })
+    : '';
+  const publicTarget = publicTargetForScope(normalizedScope, workspace, record);
+  const restoreCapability = publicTarget ? publicTargetRestoreCapability(publicTarget) : PublicTargetRestoreCapability.invalid;
+  const publicUrl = restoreCapability === PublicTargetRestoreCapability.restorable
+    ? buildPublicViewerTargetUrl(publicTarget, publicViewerUrl)
+    : '';
+  const localMaterial = localMaterialForScope(normalizedScope, workspace, record);
+  const sourceBacked = sourceBackedForScope(normalizedScope, workspace, record);
+  const targetStatus = shareTargetStatus({ publicTarget, publicUrl, exactStateUrl, localMaterial, sourceBacked, restoreCapability });
+  const accessStatus = shareAccessStatus({ scope: normalizedScope, publicTarget, workspace, record, restoreCapability });
+  const warnings = shareWarnings({ targetStatus, publicTarget, publicUrl, exactStateUrl, localMaterial, restoreCapability });
+  const allowedActions = [];
+  if (publicUrl) allowedActions.push('copy-public-url');
+  if (exactStateUrl) allowedActions.push('copy-exact-state-url');
+  return deepFreeze({
+    schema: SHARE_PROJECTION_SCHEMA,
+    scope: normalizedScope,
+    publicTarget,
+    publicUrl,
+    exactStateUrl,
+    restoreCapability,
+    targetStatus,
+    accessStatus,
+    localMaterialWarning: warnings.find((warning) => warning.code === 'share.local-material-not-carried') || null,
+    warnings,
+    allowedActions
+  });
+}
+
+export function buildExactStateUrl(state = {}, { baseUrl = '', routeCodec = globalThis.TiinexWorkspaceRoute, persistenceCodec = globalThis.TiinexWorkspacePersistence } = {}) {
+  const base = safeHttpUrl(baseUrl);
+  if (!base || typeof routeCodec?.makeRouteState !== 'function' || typeof persistenceCodec?.encodeState !== 'function') return '';
+  const routeState = routeCodec.makeRouteState(state || {});
+  const encoded = persistenceCodec.encodeState(routeState);
+  if (!encoded) return '';
+  const url = new URL(base);
+  url.hash = `state=${encoded}`;
+  return url.href;
+}
+
+function publicTargetForScope(scope, workspace, record) {
+  if (scope === ShareScope.artifact) return artifactPublicTargetFromRecord(record || {});
+  if (scope === ShareScope.workspace) return publicTargetFromWorkspace(workspace || {});
+  if (scope === ShareScope.workspaceSet) {
+    const target = publicTargetFromRecord(record || {});
+    return target?.targetKind === 'workspace' ? target : null;
+  }
+  return null;
+}
+
+function shareTargetStatus({ publicTarget, publicUrl, exactStateUrl, localMaterial, sourceBacked, restoreCapability }) {
+  if (restoreCapability === PublicTargetRestoreCapability.restorable && publicTarget && publicUrl) return ShareTargetStatus.available;
+  if (localMaterial && !publicTarget && !sourceBacked) return ShareTargetStatus.localOnly;
+  if (exactStateUrl && !publicTarget) return ShareTargetStatus.exactViewOnly;
+  return ShareTargetStatus.unavailable;
+}
+
+function shareAccessStatus({ scope, publicTarget, record, restoreCapability }) {
+  if (!publicTarget || restoreCapability !== PublicTargetRestoreCapability.restorable) return ShareAccessStatus.notApplicable;
+  if (scope === ShareScope.artifact || scope === ShareScope.workspaceSet) {
+    return explicitAuthRequired(record) ? ShareAccessStatus.accessBound : ShareAccessStatus.unknown;
+  }
+  if (scope === ShareScope.workspace) return ShareAccessStatus.unknown;
+  return ShareAccessStatus.notApplicable;
+}
+
+
+function shareWarnings({ targetStatus, publicTarget, publicUrl, exactStateUrl, localMaterial, restoreCapability }) {
+  const warnings = [];
+  if (publicTarget && restoreCapability === PublicTargetRestoreCapability.unsupported) warnings.push(warning('share.public-target-unsupported', 'This target can be described, but the current public receiver cannot reconstruct it.'));
+  if (publicTarget && restoreCapability === PublicTargetRestoreCapability.restorable && !publicUrl) warnings.push(warning('share.public-viewer-unavailable', 'A reconstructive target exists, but no configured public viewer URL can encode it.'));
+  if (localMaterial && publicTarget) warnings.push(warning('share.local-material-not-carried', 'Browser-local material is not carried by this public target.'));
+  if (targetStatus === ShareTargetStatus.exactViewOnly && exactStateUrl) warnings.push(warning('share.exact-state-not-public-material', 'The exact state URL describes semantic browser state; it does not guarantee recipient material availability.'));
+  if (targetStatus === ShareTargetStatus.localOnly) warnings.push(warning('share.local-only', 'This scope contains browser-local material without a truthful reconstructive public target.'));
+  return warnings;
+}
+
+function localMaterialForScope(scope, workspace, record) {
+  if (scope === ShareScope.artifact || scope === ShareScope.workspaceSet) return isLocalMaterial(record);
+  if (scope === ShareScope.workspace) return workspaceHasDurableLocalMaterial(workspace || {});
+  return false;
+}
+
+function sourceBackedForScope(scope, workspace, record) {
+  if (scope === ShareScope.artifact || scope === ShareScope.workspaceSet) return isSourceBackedMaterial(record);
+  if (scope !== ShareScope.workspace) return false;
+  if ((Array.isArray(workspace?.sources) ? workspace.sources : []).some(isSourceBackedSource)) return true;
+  return [...(Array.isArray(workspace?.records) ? workspace.records : []), ...(Array.isArray(workspace?.assets) ? workspace.assets : [])].some(isSourceBackedMaterial);
+}
+
+function explicitAuthRequired(record) {
+  return authRequiredIn(record?.source) || authRequiredIn(record?.sourceTarget);
+}
+
+function authRequiredIn(value = null) {
+  if (!value || typeof value !== 'object') return false;
+  return Boolean(
+    value.authRequired
+    || value.config?.authRequired
+    || value.transportPolicy?.authRequired
+    || value.diagnostics?.transportPolicy?.authRequired
+  );
+}
+
+function isLocalMaterial(value = {}) {
+  const source = value?.source || {};
+  const mode = String(value?.sourceMode || '').toLowerCase();
+  return source.id === 'local' || source.adapterId === 'local' || source.kind === 'local' || String(source.sourceKind || '').startsWith('local.') || mode.startsWith('local');
+}
+
+function isSourceBackedMaterial(value = {}) {
+  if (!value || typeof value !== 'object' || isLocalMaterial(value)) return false;
+  return Boolean(value.sourceTarget?.inputTarget || value.sourceTarget?.sourceUrl || value.sourceTarget?.rawUrl || isSourceBackedSource(value.source || {}));
+}
+
+function isSourceBackedSource(source = {}) {
+  if (!source || typeof source !== 'object') return false;
+  if (source.id === 'local' || source.adapterId === 'local' || source.kind === 'local') return false;
+  return Boolean(source.adapterId || source.sourceKind || source.repo || source.repository || source.url || source.permalink);
+}
+
+function normalizeScope(value = '') {
+  const scope = String(value || '').trim();
+  return Object.values(ShareScope).includes(scope) ? scope : ShareScope.current;
+}
+
+function warning(code, message) {
+  return Object.freeze({ code, message });
+}
+
+function safeHttpUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    return /^https?:$/.test(url.protocol) ? url.href : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}

package/src/app/shell/AppShell.js

@@ -0,0 +1 @@
+export function AppShell(model) { return model; }

package/src/app/shell/Header.js

@@ -0,0 +1 @@
+export function Header(title) { return { title }; }

package/src/app/shell/Navigation.js

@@ -0,0 +1 @@
+export function Navigation(items = []) { return items; }

package/src/app/shell/SurfaceSwitcher.js

@@ -0,0 +1 @@
+export function SurfaceSwitcher(surfaces = []) { return surfaces; }

package/src/app/sourceTransportRefresh.js

@@ -0,0 +1,176 @@
+import { nextGithubTransportTier, normalizeGithubTransportTier } from '../sources/github/github.transport.js';
+
+export const GITHUB_SOURCE_TRANSPORT_SURFACES = Object.freeze([
+  Object.freeze({ key: 'repoFiles', label: 'repo files', shortLabel: 'files', inputKey: 'repoDiscovery' }),
+  Object.freeze({ key: 'explicitFiles', label: 'explicit files', shortLabel: 'explicit', inputKey: 'explicitFiles' }),
+  Object.freeze({ key: 'issueSnapshots', label: 'issue snapshots', shortLabel: 'issues', inputKey: 'issueDiscovery' })
+]);
+
+const SURFACE_BY_KEY = Object.freeze(Object.fromEntries(GITHUB_SOURCE_TRANSPORT_SURFACES.map((surface) => [surface.key, surface])));
+
+export function sourceTransportSequenceTier(source = {}, fallbackTier = '') {
+  const outcome = source.transportOutcome || {};
+  return normalizeGithubTransportTier(
+    fallbackTier
+    || outcome.sequenceTier
+    || source.transportRefreshTier
+    || outcome.requestedTier
+    || outcome.refreshTier
+    || ''
+  ) || 'cache';
+}
+
+export function sourceTransportSurfaceState(source = {}, key = '') {
+  const surfaceKey = String(key || '').trim();
+  const requested = source.requestedSurfaces?.[surfaceKey] || {};
+  const actual = source.surfaces?.[surfaceKey] || {};
+  return Object.assign({}, requested, actual);
+}
+
+export function sourceTransportSurfaceTier(source = {}, key = '', fallbackTier = '') {
+  const surface = sourceTransportSurfaceState(source, key);
+  const list = Array.isArray(surface.transportTiers) ? surface.transportTiers.map((tier) => normalizeGithubTransportTier(tier)).filter(Boolean) : [];
+  const actualTier = normalizeGithubTransportTier(surface.transportTier || list[list.length - 1] || '');
+  return normalizeGithubTransportTier(
+    fallbackTier
+    || actualTier
+    || surface.sequenceTier
+    || surface.transportRefreshTier
+    || ''
+  ) || sourceTransportSequenceTier(source, '');
+}
+
+export function sourceTransportConfiguredSurfaces(source = {}) {
+  const keys = [];
+  const explicitFileRefs = Array.isArray(source.explicitFileRefs || source.config?.explicitFileRefs)
+    ? Array.from(source.explicitFileRefs || source.config?.explicitFileRefs).filter(Boolean)
+    : [];
+  if (source.repoDiscovery === true) keys.push('repoFiles');
+  if (explicitFileRefs.length) keys.push('explicitFiles');
+  if (source.issueDiscovery === true || Boolean(source.issueUrls || source.config?.issueUrls)) keys.push('issueSnapshots');
+  return keys;
+}
+
+export function sourceTransportActiveSurfaces(source = {}) {
+  return GITHUB_SOURCE_TRANSPORT_SURFACES.filter((surface) => {
+    const state = sourceTransportSurfaceState(source, surface.key);
+    if (state.requested || state.attempted || state.loaded || state.discovered || state.requestedCount || state.unavailable || state.skipped || state.failed) return true;
+    if (surface.key === 'repoFiles' && source.repoDiscovery) return true;
+    if (surface.key === 'issueSnapshots' && (source.issueDiscovery || source.issueUrls || source.config?.issueUrls)) return true;
+    return false;
+  }).map((surface) => surface.key);
+}
+
+export function normalizeTransportSurfaceKeys(value, source = {}) {
+  const configured = new Set(sourceTransportConfiguredSurfaces(source));
+  const requested = Array.isArray(value) ? value : String(value || '').split(',');
+  const keys = requested
+    .map((item) => String(item || '').trim())
+    .filter(Boolean)
+    .filter((key) => Boolean(SURFACE_BY_KEY[key]) && configured.has(key));
+  if (keys.length) return Array.from(new Set(keys));
+  return Array.from(configured);
+}
+
+export function sourceTransportBadgesForSource(source = {}) {
+  const activeKeys = sourceTransportActiveSurfaces(source).filter((key) => key !== 'explicitFiles');
+  if (!activeKeys.length) return [];
+  const configured = source.transportOutcome?.configured || source.transportPlan?.configured || {};
+  const configuredKeys = new Set(sourceTransportConfiguredSurfaces(source));
+  const rows = activeKeys.map((key) => {
+    const surface = sourceTransportSurfaceState(source, key);
+    const pendingTier = normalizeGithubTransportTier(surface.pendingTier || '');
+    const tier = pendingTier || sourceTransportSurfaceTier(source, key);
+    const status = String(surface.status || surface.activeStatus || (surface.unavailable || surface.skipped ? 'unavailable' : surface.failed ? 'failed' : surface.loaded ? 'ok' : '')).toLowerCase();
+    const nextTier = pendingTier ? '' : nextGithubTransportTier(tier || 'cache', configured);
+    return {
+      key,
+      label: SURFACE_BY_KEY[key]?.label || key,
+      shortLabel: SURFACE_BY_KEY[key]?.shortLabel || key,
+      tier,
+      pendingTier,
+      status,
+      nextTier,
+      refreshable: Boolean(nextTier) && configuredKeys.has(key),
+      loaded: Number(surface.loaded || 0),
+      unavailable: Boolean(surface.unavailable || surface.skipped),
+      failed: Number(surface.failed || 0) > 0
+    };
+  });
+  const tierSet = new Set(rows.map((row) => row.tier || 'cache'));
+  const pendingSet = new Set(rows.map((row) => row.pendingTier || ''));
+  const allSameTier = tierSet.size === 1 && pendingSet.size === 1;
+  if (allSameTier) {
+    const first = rows[0];
+    return [Object.assign({}, first, {
+      key: 'all',
+      surfaceKeys: rows.map((row) => row.key),
+      label: first.tier || 'transport',
+      shortLabel: '',
+      mixed: false,
+      rows,
+      refreshable: rows.some((row) => row.refreshable),
+      nextTier: first.nextTier || ''
+    })];
+  }
+  return rows.map((row) => Object.assign({}, row, { surfaceKeys: [row.key], mixed: true }));
+}
+
+export function sourceTransportRefreshInputForSource(source = {}, currentTier = '', surfaceKeysInput = null) {
+  const configured = source.transportPlan?.configured || source.transportOutcome?.configured || {};
+  const pendingTier = normalizeGithubTransportTier(source.transportOutcome?.pendingTier || '');
+  const pendingSurfaces = Array.isArray(source.transportOutcome?.pendingSurfaces) ? source.transportOutcome.pendingSurfaces : [];
+  const selectedSurfaceKeys = normalizeTransportSurfaceKeys(pendingTier ? (pendingSurfaces.length ? pendingSurfaces : surfaceKeysInput) : surfaceKeysInput, source);
+  const observedTier = pendingTier || normalizeGithubTransportTier(currentTier) || (selectedSurfaceKeys.length === 1 ? sourceTransportSurfaceTier(source, selectedSurfaceKeys[0]) : sourceTransportSequenceTier(source, currentTier));
+  const nextTier = nextGithubTransportTier(observedTier, configured);
+  if (!nextTier) return { ok: false, reason: 'last-tier', observedTier, selectedSurfaceKeys, pendingTier, pendingSurfaces };
+  const issueSurfaceSelected = selectedSurfaceKeys.includes('issueSnapshots');
+  const explicitFileSurfaceSelected = selectedSurfaceKeys.includes('explicitFiles');
+  const issueUrls = issueSurfaceSelected ? (source.issueUrls || source.config?.issueUrls || '') : '';
+  const explicitFileRefs = explicitFileSurfaceSelected && Array.isArray(source.explicitFileRefs || source.config?.explicitFileRefs)
+    ? Array.from(source.explicitFileRefs || source.config?.explicitFileRefs)
+    : [];
+  const repoDiscovery = selectedSurfaceKeys.includes('repoFiles') && source.repoDiscovery === true;
+  const issueDiscovery = issueSurfaceSelected && Boolean(source.issueDiscovery);
+  if (!repoDiscovery && !explicitFileRefs.length && !issueDiscovery && !issueUrls) return { ok: false, reason: 'no-surfaces', nextTier, observedTier, selectedSurfaceKeys, pendingTier, pendingSurfaces };
+  return {
+    ok: true,
+    nextTier,
+    observedTier,
+    selectedSurfaceKeys,
+    replacingPending: Boolean(pendingTier),
+    pendingTier,
+    pendingSurfaces,
+    input: {
+      sourceId: source.id || '',
+      repository: source.repo || source.repository || source.config?.repo || '',
+      ref: source.ref || source.config?.ref || '',
+      rootPath: source.rootPath || source.config?.rootPath || '.topics',
+      label: source.label || source.repo || 'GitHub source',
+      repoDiscovery,
+      issueDiscovery,
+      issueUrls,
+      explicitFileRefs,
+      transportRefreshTier: nextTier,
+      transportRefreshSurfaces: selectedSurfaceKeys
+    }
+  };
+}
+
+export function sourceTransportPendingUpdateInputForSource(source = {}, refresh = {}) {
+  const nextTier = normalizeGithubTransportTier(refresh.nextTier || '') || 'direct';
+  const selectedSurfaceKeys = normalizeTransportSurfaceKeys(refresh.selectedSurfaceKeys, source);
+  const repo = source.repo || source.repository || source.config?.repo || '';
+  const surfaces = Object.assign({}, source.surfaces || {});
+  for (const key of selectedSurfaceKeys) surfaces[key] = Object.assign({}, surfaces[key] || {}, { pendingTier: nextTier, transportRefreshTier: nextTier });
+  return Object.assign({}, source, {
+    id: source.id || '', repository: repo, repo,
+    ref: source.ref || source.config?.ref || '',
+    rootPath: source.rootPath || source.config?.rootPath || '.topics',
+    label: source.label || source.repo || 'GitHub source',
+    discoveryState: 'loading',
+    surfaces,
+    transportRefreshTier: nextTier,
+    transportOutcome: Object.assign({}, source.transportOutcome || {}, { pendingTier: nextTier, pendingFromTier: refresh.observedTier || source.transportRefreshTier || '', pendingSurfaces: selectedSurfaceKeys })
+  });
+}

package/src/app/startupOwnership.js

@@ -0,0 +1,40 @@
+export function createStartupOwnershipGate() {
+  let generation = 0;
+  return {
+    claim() { generation += 1; return generation; },
+    invalidate() { generation += 1; return generation; },
+    isCurrent(token) { return token === generation; },
+    current() { return generation; }
+  };
+}
+
+export async function runOwnedWorkspaceStartupTransition({
+  gate,
+  runTransition,
+  transitionOptions = {},
+  setPhase = null,
+  setNotice = null
+} = {}) {
+  if (!gate || typeof gate.claim !== 'function' || typeof gate.isCurrent !== 'function') {
+    throw new Error('startup.ownership-gate-required');
+  }
+  if (typeof runTransition !== 'function') throw new Error('startup.transition-runner-required');
+  const token = gate.claim();
+  const isCurrentOwner = () => gate.isCurrent(token);
+  setPhase?.('resolving');
+  const sourceCommit = transitionOptions.commit;
+  const sourceMaterialize = transitionOptions.materializeSource;
+  const sourceDiagnostics = transitionOptions.setDiagnostics;
+  const result = await runTransition(Object.assign({}, transitionOptions, {
+    commit: (...args) => isCurrentOwner() ? sourceCommit?.(...args) : null,
+    setDiagnostics: (...args) => isCurrentOwner() ? sourceDiagnostics?.(...args) : null,
+    materializeSource: async (input, options = {}) => {
+      if (!isCurrentOwner()) return { ok: false, skipped: 'stale-startup-owner' };
+      return sourceMaterialize?.(input, Object.assign({}, options, { isCurrentOwner }));
+    }
+  }));
+  if (!isCurrentOwner()) return Object.assign({}, result, { stale: true, ownershipToken: token });
+  setPhase?.(result?.ok ? 'resolved' : 'failed');
+  if (!result?.ok && result?.message) setNotice?.(result.message);
+  return Object.assign({}, result, { stale: false, ownershipToken: token });
+}

package/src/app/startupPresentation.case.mjs

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { startupPresentationFor } from './startupPresentation.js';
+
+assert.equal(startupPresentationFor({ startupPhase: 'resolved', state: {} }), null, 'normal product stage owns resolved startup');
+assert.equal(startupPresentationFor({ startupPhase: 'failed', state: {} }), null, 'existing product failure path owns failed startup');
+
+const clean = startupPresentationFor({ startupPhase: 'resolving', state: { workspaces: [], activeWorkspaceId: '' } });
+assert.equal(clean?.message, 'Opening workspace', 'first paint must be truthful without guessing default ownership');
+assert.equal(clean?.workspaceCount, 0);
+
+const explicit = startupPresentationFor({ startupPhase: 'resolving', state: {
+  activeWorkspaceId: 'workspace:explicit',
+  workspaces: [{
+    id: 'workspace:explicit',
+    name: 'Explicit query workspace',
+    discoveryProgress: { active: true, label: 'Opening Explicit query workspace workspace' },
+    workspaceBootstrap: { schema: 'tiinex.workspace.bootstrap.v1', startState: 'explicit-runtime-config', workspaceSetSize: 1 }
+  }]
+} });
+assert.equal(explicit?.message, 'Opening Explicit query workspace workspace', 'owned explicit progress may become visible once startup has actually selected it');
+assert.equal(explicit?.ownedWorkspaceId, 'workspace:explicit');
+assert(!explicit?.message.includes('Tiinex docs'), 'explicit resolving presentation must not visually substitute embedded/default ownership');
+
+const multi = startupPresentationFor({ startupPhase: 'resolving', state: {
+  activeWorkspaceId: 'workspace:a',
+  workspaces: [
+    { id: 'workspace:a', discoveryProgress: { active: true, label: 'Opening A workspace' }, workspaceBootstrap: { schema: 'tiinex.workspace.bootstrap.v1', workspaceSetSize: 2, workspaceSetIndex: 0 } },
+    { id: 'workspace:b', discoveryProgress: { active: true, label: 'Opening B workspace' }, workspaceBootstrap: { schema: 'tiinex.workspace.bootstrap.v1', workspaceSetSize: 2, workspaceSetIndex: 1 } }
+  ]
+} });
+assert.equal(multi?.message, 'Opening 2 configured workspaces', 'multi-entrypoint startup must not collapse presentation to one guessed source');
+assert.equal(multi?.workspaceCount, 2);
+
+console.log('✓ startup presentation model tests passed');

package/src/app/startupPresentation.js

@@ -0,0 +1,33 @@
+export const STARTUP_PRESENTATION_KIND = 'startup-resolving';
+
+export function startupPresentationFor({ startupPhase = 'resolving', state = {} } = {}) {
+  if (startupPhase !== 'resolving') return null;
+  const workspaces = Array.isArray(state?.workspaces) ? state.workspaces : [];
+  const owned = workspaces.filter((workspace) => hasStartupPresentationAuthority(workspace));
+  const activeId = String(state?.activeWorkspaceId || '').trim();
+  const active = owned.find((workspace) => String(workspace?.id || '') === activeId) || owned[0] || null;
+  const declaredSize = owned.reduce((size, workspace) => Math.max(size, Number(workspace?.workspaceBootstrap?.workspaceSetSize || 0)), 0);
+  const workspaceCount = Math.max(declaredSize, owned.length);
+  const ownedMessage = cleanMessage(active?.discoveryProgress?.label || active?.workspaceBootstrap?.userFacingMessage || '');
+  const message = workspaceCount > 1
+    ? `Opening ${workspaceCount} configured workspaces`
+    : (ownedMessage || 'Opening workspace');
+  return Object.freeze({
+    kind: STARTUP_PRESENTATION_KIND,
+    message,
+    workspaceCount,
+    ownedWorkspaceId: String(active?.id || '')
+  });
+}
+
+function hasStartupPresentationAuthority(workspace = {}) {
+  return Boolean(
+    workspace?.discoveryProgress?.active
+    || workspace?.workspaceBootstrap?.schema === 'tiinex.workspace.bootstrap.v1'
+    || workspace?.workspaceBootstrap?.startState
+  );
+}
+
+function cleanMessage(value = '') {
+  return String(value || '').trim().replace(/[.\s]+$/u, '');
+}

package/src/app/startupPresentation.views.jsx

@@ -0,0 +1,21 @@
+import React from 'react';
+
+const LOGO_SRC = `${import.meta.env.BASE_URL}assets/tiinex-logo-white-transparent.png`;
+
+export function StartupStage({ presentation = null, runtimeId = '', sourceBoundary = '' }) {
+  if (!presentation) return null;
+  return (
+    <main
+      className="tx-react-runtime tx-uc001-shell tx-startup-resolving-shell"
+      data-runtime={runtimeId}
+      data-source-boundary={sourceBoundary}
+      data-startup-presentation={presentation.kind || 'startup-resolving'}
+    >
+      <section className="tx-startup-stage" role="status" aria-live="polite" aria-label="Opening Tiinex workspace">
+        <img className="tx-startup-logo" src={LOGO_SRC} alt="" />
+        <p>{presentation.message || 'Opening workspace'}</p>
+        <span className="tx-startup-progress" aria-hidden="true"><i /><i /><i /></span>
+      </section>
+    </main>
+  );
+}

package/src/app/startupRenderPhase.js

@@ -0,0 +1,9 @@
+export function initialStartupRenderPhase({ locationLike = null, routeResolved = false } = {}) {
+  const hash = String(locationLike?.hash || '');
+  if (!hash.startsWith('#state=')) return 'resolving';
+  return routeResolved ? 'resolved' : 'resolving';
+}
+
+export function shouldRenderProductStage(startupPhase = 'resolving') {
+  return startupPhase === 'resolved' || startupPhase === 'failed';
+}

package/src/app/startupWorkspaceCommand.js

@@ -0,0 +1,62 @@
+import { stateWithDefaultWorkspaceStartProgress } from './defaultWorkspaceStart.js';
+import { openWorkspaceEntrypointSet } from '../workspaces/workspace.entrypointLifecycle.js';
+
+export function prepareResolvedStartupWorkspaceCommand({ lifecycle, persistence, state = {}, resolved = {}, storage = null } = {}) {
+  const resolvedInputs = (Array.isArray(resolved?.inputs) ? resolved.inputs : [resolved?.input]).filter(Boolean);
+  if (!resolved?.ok || !resolvedInputs.length) return { ok: false, error: 'startup.config-unavailable', message: resolved?.message || 'Startup workspace config is unavailable.', state, resolved };
+  if (!lifecycle?.createWorkspace) return { ok: false, error: 'workspace.lifecycle-unavailable', message: 'Workspace lifecycle is unavailable.', state, resolved };
+  const inputs = resolvedInputs.map((sourceInput) => Object.assign({}, sourceInput, {
+    bootstrapStartState: resolved.startupClass || 'configured-workspace',
+    bootstrapBoundary: 'resolved-startup-config'
+  }));
+  const opened = openWorkspaceEntrypointSet({
+    lifecycle,
+    state,
+    sourceInputs: inputs,
+    entry: { title: resolved.config?.viewerIdentity?.browserTitle || 'Tiinex workspace set', markdown: resolved.markdown || '', path: resolved.configUrl || resolved.targetUrl || '' },
+    workspaceInput(sourceInput, index) {
+      const name = sourceInput.label || resolved.config?.viewerIdentity?.browserTitle || sourceInput.repository || `Tiinex workspace ${index + 1}`;
+      const id = inputs.length === 1
+        ? stableStartupWorkspaceId(resolved.configUrl || resolved.targetUrl || name)
+        : stableStartupWorkspaceId(`${resolved.configUrl || resolved.targetUrl || 'tiinex-startup'}#${index}:${name}:${sourceInput.repository || ''}`);
+      return { id, name, boundary: 'resolved Tiinex startup config; source materialization is explicit' };
+    },
+    afterCreate({ state: createdState, workspace, sourceInput }) {
+      let nextState = persistence?.hydrateWorkspaceWithLocalDeltas?.(createdState, workspace?.id, storage) || createdState;
+      let target = (nextState.workspaces || []).find((item) => item.id === workspace?.id) || workspace;
+      if (target && resolved.markdown) target.workspaceMarkdown = resolved.markdown;
+      nextState = stateWithDefaultWorkspaceStartProgress(nextState, workspace?.id, { input: sourceInput });
+      return nextState;
+    },
+    registerSources: false,
+    annotateWorkspace({ state: nextState, workspaceId, index }) {
+      const workspace = (nextState.workspaces || []).find((item) => item.id === workspaceId);
+      if (!workspace) return;
+      workspace.workspaceConfig = resolved.config && typeof resolved.config === 'object' ? JSON.parse(JSON.stringify(resolved.config)) : null;
+      workspace.workspaceBootstrap = Object.assign({}, workspace.workspaceBootstrap || {}, {
+        schema: 'tiinex.workspace.bootstrap.v1',
+        startState: resolved.startupClass || 'configured-workspace',
+        boundary: 'resolved-startup-config',
+        configUrl: resolved.configUrl || resolved.targetUrl || '',
+        selectedConvention: resolved.diagnostics?.selectedConvention || '',
+        usefulStartPath: 'resolved-config-workspace-set-materialization-queued',
+        workspaceSetSize: inputs.length,
+        workspaceSetIndex: index
+      });
+    }
+  });
+  if (!opened?.ok) return { ok: false, error: opened?.error || 'startup.workspace-create-failed', message: opened?.message || 'Could not create startup workspace set.', state, resolved };
+  return Object.assign({}, opened, {
+    resolved,
+    sourceInput: opened.sourceInputs?.[0] || null,
+    notice: inputs.length > 1 ? `Opening ${inputs.length} configured workspaces.` : `Opening ${opened.workspace?.title || opened.workspace?.name || 'workspace'}.`
+  });
+}
+
+
+export function stableStartupWorkspaceId(value = '') {
+  const text = String(value || 'tiinex-startup');
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) { hash ^= text.charCodeAt(index); hash = Math.imul(hash, 16777619); }
+  return `workspace:startup:${(hash >>> 0).toString(36)}`;
+}

package/src/app/startupWorkspaceConfigApplication.js

@@ -0,0 +1,49 @@
+import { isWorkspaceEntrypointArtifact } from '@tiinex/core/workspaces/workspace.entrypointCapability.js';
+import { openWorkspaceRecordAction } from './workspaceRecordActions.js';
+
+export function applyMaterializedStartupWorkspaceConfig({ runtimeApi = {}, state = {}, resolved = {}, discoveryWorkspaceId = '' } = {}) {
+  if (resolved?.selectedPlan !== 'workspace-discovery') return { ok: true, applied: false, state };
+  const workspace = workspaceById(state, discoveryWorkspaceId || state.activeWorkspaceId);
+  if (!workspace) return { ok: false, error: 'startup.discovery-workspace-missing', message: 'Startup workspace discovery materialized without a workspace owner.', state };
+  const candidates = (Array.isArray(workspace.records) ? workspace.records : []).filter((record) => isWorkspaceEntrypointArtifact(record) && String(record.markdown || '').trim());
+  const selected = selectStartupWorkspaceArtifact(candidates, resolved?.input?.workspaceMatch || '');
+  if (!selected.ok) return Object.assign({}, selected, { state, workspace });
+  const opened = openWorkspaceRecordAction({ lifecycle: runtimeApi.lifecycle, parseWorkspaceConfig: runtimeApi.config?.parseWorkspaceConfig, state, record: selected.record });
+  if (!opened?.ok) return { ok: false, error: opened?.error || 'startup.workspace-artifact-open-failed', message: opened?.message || 'Could not apply the discovered startup workspace artifact.', state, workspace, record: selected.record };
+  return Object.assign({}, opened, { applied: true, startupRecord: selected.record, discoveryWorkspaceId: workspace.id });
+}
+
+export function selectStartupWorkspaceArtifact(records = [], workspaceMatch = '') {
+  const list = Array.isArray(records) ? records : [];
+  if (!list.length) return { ok: false, error: 'startup.workspace-artifact-missing', message: 'Startup discovery did not materialize an openable workspace artifact.' };
+  const pattern = String(workspaceMatch || '').trim();
+  if (pattern) {
+    const matched = list.filter((record) => workspaceArtifactMatches(record, pattern));
+    if (matched.length === 1) return { ok: true, record: matched[0] };
+    if (matched.length > 1) return { ok: false, error: 'startup.workspace-artifact-ambiguous', message: 'Startup workspace match resolved to more than one workspace artifact.' };
+    return { ok: false, error: 'startup.workspace-artifact-match-missing', message: 'Startup workspace match did not resolve to a materialized workspace artifact.' };
+  }
+  if (list.length === 1) return { ok: true, record: list[0] };
+  return { ok: false, error: 'startup.workspace-artifact-ambiguous', message: 'Startup discovery materialized multiple workspace artifacts without a unique match.' };
+}
+
+function workspaceArtifactMatches(record = {}, pattern = '') {
+  const values = [record.path, record.sourceTarget?.sourceArtifactPath, record.title, record.name].map((value) => String(value || '').trim()).filter(Boolean);
+  const cleanPattern = String(pattern || '').trim().replace(/\\/g, '/');
+  const regex = wildcardRegex(cleanPattern);
+  return values.some((value) => {
+    const cleanValue = String(value || '').replace(/\\/g, '/');
+    if (regex.test(cleanValue)) return true;
+    if (!cleanPattern.includes('/')) return regex.test(cleanValue.split('/').filter(Boolean).pop() || '');
+    return false;
+  });
+}
+
+function wildcardRegex(pattern = '') {
+  const escaped = String(pattern || '').replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`, 'i');
+}
+
+function workspaceById(state = {}, workspaceId = '') {
+  return (Array.isArray(state?.workspaces) ? state.workspaces : []).find((workspace) => String(workspace?.id || '') === String(workspaceId || '')) || null;
+}