@tiinex/app 0.1.1

package/src/app/statePersistenceScheduler.js

@@ -0,0 +1,106 @@
+import { canonicalProductState } from './productStateBoundary.js';
+import { persistenceWriteEnvForOwnership } from './persistenceOwnership.js';
+
+export function createStatePersistenceScheduler(win = globalThis, options = {}) {
+  const state = {
+    timer: null,
+    idle: null,
+    pending: null,
+    writes: 0,
+    deferred: 0,
+    flushed: 0,
+    lastReason: ''
+  };
+
+  const clearTimer = () => {
+    if (state.timer && win?.clearTimeout) win.clearTimeout(state.timer);
+    state.timer = null;
+  };
+  const clearIdle = () => {
+    if (state.idle && typeof win?.cancelIdleCallback === 'function') win.cancelIdleCallback(state.idle);
+    state.idle = null;
+  };
+  const clearScheduled = () => { clearTimer(); clearIdle(); };
+
+  function writeNow(entry, reason = 'write') {
+    if (!entry?.state?.workspaces?.length) return null;
+    state.writes += 1;
+    state.lastReason = reason;
+    entry.runtime?.().persistence?.writeState?.(entry.state, persistenceWriteEnvForOwnership(options.persistenceOwnership, { mode: entry.mode || 'replace' }));
+    return entry.state;
+  }
+
+  function flush(reason = 'flush') {
+    const entry = state.pending;
+    state.pending = null;
+    clearScheduled();
+    if (!entry) return null;
+    state.flushed += 1;
+    return writeNow(entry, reason);
+  }
+
+  function schedule(entry = {}, options = {}) {
+    if (!entry?.state?.workspaces?.length) return null;
+    state.pending = entry;
+    state.deferred += 1;
+    state.lastReason = options.reason || 'deferred';
+    clearScheduled();
+    const delayMs = Math.max(0, Number(options.delayMs ?? 180));
+    const idleTimeout = Math.max(0, Number(options.idleTimeout ?? 1600));
+    const run = () => {
+      state.timer = null;
+      const idleRun = () => {
+        state.idle = null;
+        flush(options.reason || 'idle');
+      };
+      if (typeof win?.requestIdleCallback === 'function') state.idle = win.requestIdleCallback(idleRun, { timeout: idleTimeout });
+      else state.timer = win?.setTimeout?.(idleRun, Math.max(60, Math.min(450, idleTimeout))) || null;
+    };
+    state.timer = win?.setTimeout?.(run, delayMs) || null;
+    return entry.state;
+  }
+
+  function cancel() {
+    state.pending = null;
+    clearScheduled();
+  }
+
+  function report() {
+    return {
+      pending: Boolean(state.pending),
+      writes: state.writes,
+      deferred: state.deferred,
+      flushed: state.flushed,
+      lastReason: state.lastReason
+    };
+  }
+
+  return { schedule, flush, cancel, report };
+}
+
+
+export function commitStateWithPersistence({ nextState, mode = 'push', options = {}, sourceState = {}, preserveCapturedViewScroll, latestStateRef, setState, runtime, scheduler, persistenceOwnership } = {}) {
+  const withScroll = preserveCapturedViewScroll?.(nextState, sourceState) || nextState;
+  const persistence = runtime?.().persistence || {};
+  const canonicalState = canonicalProductState(withScroll, persistence, 'commit');
+  if (latestStateRef) latestStateRef.current = canonicalState;
+  setState?.(canonicalState);
+  const persistenceEnv = persistenceWriteEnvForOwnership(persistenceOwnership, { mode, preserveUrl: Boolean(options.preserveUrl) });
+  if (!canonicalState?.workspaces?.length) {
+    scheduler?.cancel?.();
+    if (options.allowEmptySemanticState) persistence.writeState?.(canonicalState, persistenceEnv);
+    else persistence.clearState?.(persistenceEnv);
+    return canonicalState;
+  }
+  if (options.deferPersistence) {
+    scheduler?.schedule?.({ state: canonicalState, mode, runtime }, {
+      reason: options.persistenceReason || 'view-state',
+      delayMs: options.persistenceDelayMs,
+      idleTimeout: options.persistenceIdleTimeout
+    });
+    return canonicalState;
+  }
+  scheduler?.cancel?.();
+  persistence.writeState?.(canonicalState, persistenceEnv);
+  return canonicalState;
+}

package/src/app/tiinexAppConfigPlan.js

@@ -0,0 +1,108 @@
+import { workspaceEntrypointApplies } from '../workspaces/workspace.entrypoints.js';
+
+export function tiinexAppConfigSourceToStartupPlan(result = {}) {
+  const config = result.config || {};
+  const entrypoints = (Array.isArray(config.workspaceEntrypoints) ? config.workspaceEntrypoints : [])
+    .filter(workspaceEntrypointApplies)
+    .map((entrypoint, index) => workspaceSourceToGithubInput(entrypoint, {
+      result,
+      config,
+      plan: 'workspace-entrypoints',
+      preserveView: false,
+      preferredDisplay: '',
+      fallbackLabel: entrypoint.workspaceLabel || entrypoint.label || entrypoint.name || `Workspace ${index + 1}`
+    }))
+    .filter(Boolean);
+  if (entrypoints.length) return { ok: true, selectedPlan: 'workspace-entrypoints', input: entrypoints[0], inputs: entrypoints };
+  const discovery = firstWorkspaceDiscovery(config);
+  const mappedDiscovery = workspaceSourceToGithubInput(discovery, {
+    result,
+    config,
+    plan: 'workspace-discovery',
+    preserveView: true,
+    preferredDisplay: 'workspace-artifacts',
+    fallbackLabel: discovery?.label || discovery?.title || config.viewerIdentity?.browserTitle || ''
+  });
+  if (mappedDiscovery) return { ok: true, selectedPlan: 'workspace-discovery', input: mappedDiscovery, inputs: [mappedDiscovery] };
+  return { ok: false, message: 'The Tiinex app config did not declare an openable workspace entrypoint or GitHub workspace discovery target.' };
+}
+
+export function tiinexAppConfigSourceToGithubInput(result = {}) {
+  const config = result.config || {};
+  const explicitEntrypoint = result.entrypoint && workspaceEntrypointApplies(result.entrypoint) ? result.entrypoint : null;
+  const entrypoint = explicitEntrypoint || firstWorkspaceEntrypoint(config);
+  const preferEntrypoint = shouldPreferWorkspaceEntrypoint(result);
+  const discovery = preferEntrypoint ? null : firstWorkspaceDiscovery(config);
+  const source = discovery || entrypoint;
+  const input = workspaceSourceToGithubInput(source, {
+    result,
+    config,
+    plan: discovery ? 'workspace-discovery' : 'workspace-entrypoint',
+    preserveView: Boolean(discovery),
+    preferredDisplay: discovery ? 'workspace-artifacts' : '',
+    fallbackLabel: source?.label || source?.name || source?.title || config.viewerIdentity?.browserTitle || ''
+  });
+  if (!input) return { ok: false, message: 'The Tiinex app config did not declare a GitHub repository or workspace discovery target.' };
+  return { ok: true, selectedPlan: discovery ? 'workspace-discovery' : 'workspace-entrypoint', input };
+}
+
+function workspaceSourceToGithubInput(source = null, { result = {}, config = {}, plan = 'workspace-entrypoint', preserveView = false, preferredDisplay = '', fallbackLabel = '' } = {}) {
+  if (!source) return null;
+  const sourceKind = String(source?.sourceKind || source?.kind || '').trim() || 'github-tree';
+  const repository = String(source?.repository || source?.repo || githubRepositoryFromUrl(source?.href || source?.url || '') || '').trim();
+  if (!repository) return null;
+  const discoveryMode = plan === 'workspace-discovery';
+  return {
+    repository,
+    ref: source.ref || '',
+    rootPath: source.rootPath || '.topics',
+    operation: 'materialize',
+    repoDiscovery: discoveryMode ? true : truthyConfigValue(source.repoFilesDiscovery ?? source.repoDiscovery ?? true),
+    issueDiscovery: discoveryMode ? false : truthyConfigValue(source.issueDiscovery ?? source.issueSnapshots ?? false),
+    issueUrls: discoveryMode ? '' : (source.issueUrl || source.issueUrls || ''),
+    label: source.workspaceLabel || source.label || source.name || source.title || fallbackLabel || config.viewerIdentity?.browserTitle || repository,
+    workspaceLabel: source.workspaceLabel || source.label || source.name || source.title || fallbackLabel || config.viewerIdentity?.browserTitle || repository,
+    fileRefs: source.fileRefs || source.explicitMarkdownPaths || '',
+    sourceKind,
+    appConfigSourceUrl: result.configUrl || result.targetUrl || '',
+    appConfigPlan: plan,
+    workspaceMatch: source.match || source.pattern || '',
+    openBehavior: source.openBehavior || '',
+    preserveView,
+    preferredDisplay,
+    hostedRepoMirrorBaseUrls: source.hostedRepoMirrorBaseUrls || source.repositoryMirrorBaseUrls || [],
+    hostedIssueSnapshotBaseUrls: source.hostedIssueSnapshotBaseUrls || source.mirrorIssueSnapshotBaseUrls || []
+  };
+}
+
+function shouldPreferWorkspaceEntrypoint(result = {}) {
+  const convention = String(result?.diagnostics?.selectedConvention || '').toLowerCase();
+  return /github-issue|public-build-issue-sync|workspace-state/.test(convention);
+}
+
+function firstWorkspaceEntrypoint(config = {}) {
+  return Array.isArray(config.workspaceEntrypoints) ? config.workspaceEntrypoints.find(workspaceEntrypointApplies) || null : null;
+}
+
+function firstWorkspaceDiscovery(config = {}) {
+  const items = Array.isArray(config.workspaceDiscovery) ? config.workspaceDiscovery : [];
+  return items.find((item) => String(item?.kind || item?.sourceKind || '').trim().toLowerCase().includes('github') || githubRepositoryFromUrl(item?.href || item?.url || '') || item?.repository || item?.repo) || items[0] || null;
+}
+
+function githubRepositoryFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+    if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+  } catch (_) {}
+  const match = String(value || '').trim().match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:\.git)?$/u);
+  return match ? `${match[1]}/${match[2]}` : '';
+}
+
+function truthyConfigValue(value) {
+  if (typeof value === 'boolean') return value;
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) return false;
+  return !['off', 'false', 'no', '0', 'disabled'].includes(text);
+}

package/src/app/tiinexAppConfigSource.js

@@ -0,0 +1,349 @@
+import { extractConfigLinks, extractEmbeddedWorkspaceMarkdowns, extractHostedViewerSourceDeclarations, extractRuntimeWorkspaceDeclarations, extractScriptUrls, isLikelyConfigUrl, looksLikeWorkspaceConfig, normalizeConfigTargetUrl, normalizeNewlines, normalizeWorkspaceBootstrapCandidate, parseGithubIssueSpec, sameOriginOrExplicit, scriptFileName, sourceDeclarationFromPublicBuildIdentity, toFetchableWorkspaceUrl, tryFetchText, workspaceUrlFromPointerMarkdown } from './tiinexHostedWorkspaceConventions.js';
+import { tiinexAppConfigSourceToGithubInput, tiinexAppConfigSourceToStartupPlan } from './tiinexAppConfigPlan.js';
+import { workspaceEntrypointApplies } from '../workspaces/workspace.entrypoints.js';
+export { tiinexAppConfigSourceToGithubInput, tiinexAppConfigSourceToStartupPlan } from './tiinexAppConfigPlan.js';
+
+const DEFAULT_CONFIG_PATHS = Object.freeze([
+  '/.well-known/tiinex/workspace.md',
+  '/tiinex.workspace.md',
+  '/viewer.workspace.md',
+  '/workspace.md',
+  '/.topics/.workspaces/viewer.workspace.md'
+]);
+
+const MAX_SCRIPT_CANDIDATES = 8;
+
+export function tiinexAppConfigUrlCandidates(targetUrl = '', options = {}) {
+  const url = normalizeConfigTargetUrl(targetUrl, options.baseUrl);
+  if (!url) return [];
+  const candidates = [];
+  const add = (value) => {
+    try {
+      const href = toFetchableWorkspaceUrl(new URL(value, url).href);
+      if (!candidates.includes(href)) candidates.push(href);
+    } catch (_) {}
+  };
+  if (isLikelyConfigUrl(url)) add(url.href);
+  for (const path of DEFAULT_CONFIG_PATHS) add(`${url.origin}${path}`);
+  return candidates;
+}
+
+async function firstReadableWorkspaceConfig(candidates = [], context = {}) {
+  const { fetchImpl, target, parseWorkspaceConfig, diagnostics, selectedConvention } = context;
+  for (const href of candidates || []) {
+    const fetched = await tryFetchText(fetchImpl, href, 'text/markdown,text/plain,application/json,*/*');
+    if (!fetched.ok || !looksLikeWorkspaceConfig(fetched.text)) continue;
+    return successFromMarkdown({ markdown: fetched.text, configUrl: href, target, parseWorkspaceConfig, diagnostics: Object.assign({}, diagnostics, { selectedConvention }) });
+  }
+  return null;
+}
+
+export async function fetchTiinexAppConfigSource(targetUrl = '', options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const parseWorkspaceConfig = options.parseWorkspaceConfig || ((markdown) => ({ workspaceEntrypoints: [] }));
+  const target = normalizeConfigTargetUrl(targetUrl, options.baseUrl);
+  if (!target) return failure('Enter a Tiinex app URL.');
+  if (typeof fetchImpl !== 'function') return failure('Fetch is unavailable in this browser.');
+
+  const explicitCandidates = [];
+  const fallbackCandidates = [];
+  const runtimeCandidates = [];
+  const embeddedWorkspaces = [];
+  const hostedViewerSources = [];
+  const scriptUrls = [];
+  const diagnostics = { html: 'unavailable', candidates: [], explicitCandidates, fallbackCandidates, runtimeCandidates: [], hostedViewerSources: [], scripts: [], publicBuildIdentity: null };
+
+  const addCandidate = (value, source = 'explicit') => {
+    try {
+      const href = toFetchableWorkspaceUrl(new URL(value, target).href);
+      const bucket = source === 'convention-path' ? fallbackCandidates : explicitCandidates;
+      if (!bucket.includes(href)) bucket.push(href);
+      if (!diagnostics.candidates.includes(href)) diagnostics.candidates.push(href);
+      return href;
+    } catch (_) { return ''; }
+  };
+  const addRuntimeCandidate = (candidate, source = '') => {
+    const normalized = normalizeWorkspaceBootstrapCandidate(candidate, { source, role: source || 'hosted-runtime' });
+    if (!normalized) return;
+    const key = `${normalized.kind}\n${normalized.url || ''}\n${normalized.path || ''}`;
+    if (runtimeCandidates.some((item) => `${item.kind}\n${item.url || ''}\n${item.path || ''}` === key)) return;
+    runtimeCandidates.push(normalized);
+    diagnostics.runtimeCandidates.push({ kind: normalized.kind, role: normalized.role || '', source: normalized.source || source || '', url: normalized.url || '', path: normalized.path || '' });
+  };
+  const addEmbeddedWorkspace = (markdown, sourceUrl = '') => {
+    if (!looksLikeWorkspaceConfig(markdown)) return;
+    embeddedWorkspaces.push({ markdown, sourceUrl: sourceUrl || target.href });
+  };
+  const addHostedViewerSource = (source = {}, sourceUrl = '') => {
+    if (!source?.repository) return;
+    const key = `${source.repository}\n${source.ref || ''}\n${source.rootPath || ''}`;
+    if (hostedViewerSources.some((item) => `${item.repository}\n${item.ref || ''}\n${item.rootPath || ''}` === key)) return;
+    const item = Object.assign({ sourceUrl: sourceUrl || target.href }, source);
+    hostedViewerSources.push(item);
+    diagnostics.hostedViewerSources.push({ repository: item.repository, ref: item.ref || '', rootPath: item.rootPath || '', sourceUrl: item.sourceUrl || '', convention: item.hostedConvention || '' });
+  };
+
+  if (isLikelyConfigUrl(target)) addCandidate(target.href, 'target-url');
+
+  const html = await tryFetchText(fetchImpl, target.href, 'text/html,application/xhtml+xml,text/plain,*/*');
+  if (html.ok) {
+    diagnostics.html = 'read';
+    extractConfigLinks(html.text, target.href).forEach((href) => addCandidate(href, 'html-link'));
+    extractScriptUrls(html.text, target.href).forEach((href) => {
+      if (!scriptUrls.includes(href) && sameOriginOrExplicit(href, target.href)) scriptUrls.push(href);
+    });
+    extractRuntimeWorkspaceDeclarations(html.text, target.href).forEach((candidate) => addRuntimeCandidate(candidate, 'html-runtime'));
+    extractHostedViewerSourceDeclarations(html.text, target.href).forEach((source) => addHostedViewerSource(source, target.href));
+    extractEmbeddedWorkspaceMarkdowns(html.text, target.href).forEach((item) => addEmbeddedWorkspace(item.markdown, item.sourceUrl || target.href));
+  } else {
+    diagnostics.html = html.reason || 'unavailable';
+  }
+
+  for (const href of scriptUrls.slice(0, MAX_SCRIPT_CANDIDATES)) {
+    const script = await tryFetchText(fetchImpl, href, 'application/javascript,text/javascript,text/plain,*/*');
+    diagnostics.scripts.push({ url: href, ok: script.ok, reason: script.ok ? 'read' : script.reason || 'unavailable' });
+    if (!script.ok) continue;
+    extractConfigLinks(script.text, href).forEach((link) => addCandidate(link, 'script-link'));
+    extractRuntimeWorkspaceDeclarations(script.text, href).forEach((candidate) => addRuntimeCandidate(candidate, `script:${scriptFileName(href)}`));
+    extractHostedViewerSourceDeclarations(script.text, href).forEach((source) => addHostedViewerSource(source, href));
+    extractEmbeddedWorkspaceMarkdowns(script.text, href).forEach((item) => addEmbeddedWorkspace(item.markdown, item.sourceUrl || href));
+  }
+
+
+  const buildIdentityUrl = publicBuildIdentityUrlFor(target);
+  if (buildIdentityUrl) {
+    const buildIdentity = await tryFetchText(fetchImpl, buildIdentityUrl, 'application/json,text/plain,*/*');
+    diagnostics.publicBuildIdentity = { url: buildIdentityUrl, ok: buildIdentity.ok, reason: buildIdentity.ok ? 'read' : buildIdentity.reason || 'unavailable' };
+    if (buildIdentity.ok) {
+      const pointer = workspacePointerCandidateFromPublicBuildIdentity(buildIdentity.text, buildIdentityUrl);
+      if (pointer) addRuntimeCandidate(pointer, 'public-build-identity');
+      const source = sourceDeclarationFromPublicBuildIdentity(buildIdentity.text, buildIdentityUrl);
+      if (source?.repository) addHostedViewerSource(source, buildIdentityUrl);
+    }
+  }
+
+  const explicitTargetConfig = isLikelyConfigUrl(target);
+  if (explicitTargetConfig) {
+    const resolved = await firstReadableWorkspaceConfig(explicitCandidates, { fetchImpl, target, parseWorkspaceConfig, diagnostics, selectedConvention: 'explicit-config' });
+    if (resolved?.ok) return resolved;
+  }
+
+  if (!explicitTargetConfig) {
+    const resolved = await firstReadableWorkspaceConfig(strongHtmlConfigCandidates(explicitCandidates, target), { fetchImpl, target, parseWorkspaceConfig, diagnostics, selectedConvention: 'html-declared-config' });
+    if (resolved?.ok) return resolved;
+  }
+
+  for (const runtimeCandidate of runtimeCandidates) {
+    const resolved = await resolveWorkspaceBootstrapCandidate(runtimeCandidate, { fetchImpl, target, parseWorkspaceConfig, diagnostics });
+    if (resolved?.ok) return resolved;
+  }
+
+  for (const hostedSource of hostedViewerSources) {
+    return successFromHostedViewerSource({ source: hostedSource, configUrl: `${hostedSource.sourceUrl || target.href}#hosted-viewer-source`, target, diagnostics: Object.assign({}, diagnostics, { selectedConvention: hostedSource.hostedConvention || 'hosted-viewer-source' }) });
+  }
+
+  if (!explicitTargetConfig) {
+    const resolved = await firstReadableWorkspaceConfig(weakHtmlConfigCandidates(explicitCandidates, target), { fetchImpl, target, parseWorkspaceConfig, diagnostics, selectedConvention: 'html-packaged-config' });
+    if (resolved?.ok) return resolved;
+  }
+
+  for (const embedded of embeddedWorkspaces) {
+    return successFromMarkdown({ markdown: embedded.markdown, configUrl: `${embedded.sourceUrl || target.href}#embedded-default-workspace`, target, parseWorkspaceConfig, diagnostics: Object.assign({}, diagnostics, { selectedConvention: 'embedded-default-workspace' }) });
+  }
+
+  tiinexAppConfigUrlCandidates(target.href).forEach((href) => addCandidate(href, 'convention-path'));
+
+  for (const href of fallbackCandidates) {
+    const fetched = await tryFetchText(fetchImpl, href, 'text/markdown,text/plain,application/json,*/*');
+    if (!fetched.ok || !looksLikeWorkspaceConfig(fetched.text)) continue;
+    return successFromMarkdown({ markdown: fetched.text, configUrl: href, target, parseWorkspaceConfig, diagnostics: Object.assign({}, diagnostics, { selectedConvention: 'convention-path' }) });
+  }
+
+  return failure(`No Tiinex workspace config was found at ${target.origin}.`, { targetUrl: target.href, diagnostics });
+}
+
+
+export async function resolveTiinexRuntimeWorkspaceCandidate(candidate = {}, options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const parseWorkspaceConfig = options.parseWorkspaceConfig || ((markdown) => ({ workspaceEntrypoints: [] }));
+  const target = normalizeConfigTargetUrl(options.targetUrl || options.locationLike?.href || globalThis.location?.href || candidate?.url || candidate?.path || '', options.baseUrl);
+  if (!target) return failure('Tiinex runtime workspace target is unavailable.');
+  return resolveWorkspaceBootstrapCandidate(candidate, { fetchImpl, target, parseWorkspaceConfig, diagnostics: options.diagnostics || {} });
+}
+
+export async function resolveTiinexAppConfigGithubInput(targetUrl = '', options = {}) {
+  const result = await fetchTiinexAppConfigSource(targetUrl, options);
+  if (!result.ok) return result;
+  const mapped = tiinexAppConfigSourceToGithubInput(result);
+  if (!mapped.ok) return Object.assign({}, mapped, { diagnostics: result.diagnostics, configUrl: result.configUrl });
+  return Object.assign({}, mapped, { configUrl: result.configUrl, targetUrl: result.targetUrl, diagnostics: result.diagnostics });
+}
+
+
+function shouldPreferWorkspaceEntrypoint(result = {}) {
+  const convention = String(result?.diagnostics?.selectedConvention || '').toLowerCase();
+  return /github-issue|public-build-issue-sync|workspace-state/.test(convention);
+}
+
+function strongHtmlConfigCandidates(candidates = [], target) {
+  return (candidates || []).filter((href) => !isWeakPackagedWorkspaceConfigUrl(href, target));
+}
+
+function weakHtmlConfigCandidates(candidates = [], target) {
+  return (candidates || []).filter((href) => isWeakPackagedWorkspaceConfigUrl(href, target));
+}
+
+function isWeakPackagedWorkspaceConfigUrl(href = '', target) {
+  try {
+    const url = new URL(href, target?.href || undefined);
+    const path = url.pathname.replace(/\/+$/u, '');
+    return /(?:^|\/)\.topics\/\.workspaces\/viewer\.workspace\.md$/iu.test(path)
+      || /(?:^|\/)viewer\.workspace\.md$/iu.test(path);
+  } catch (_) {
+    return /(?:^|\/)\.topics\/\.workspaces\/viewer\.workspace\.md(?:[?#].*)?$/iu.test(String(href || ''))
+      || /(?:^|\/)viewer\.workspace\.md(?:[?#].*)?$/iu.test(String(href || ''));
+  }
+}
+
+function workspacePointerCandidateFromPublicBuildIdentity(text = '', baseUrl = '') {
+  let parsed = null;
+  try { parsed = JSON.parse(String(text || '').trim()); } catch (_) { return null; }
+  const repository = githubRepositoryFromUrl(parsed.repository || parsed.sourceRepository || parsed.repo || parsed.buildSource || '');
+  const reason = [parsed.reason, parsed.releaseCacheKey, parsed.previousReleaseCacheKey, parsed.type].map((value) => String(value || '').toLowerCase()).join(' ');
+  if (!repository || !/(?:^|[^a-z0-9])issue[-_]?sync(?:[^a-z0-9]|$)/iu.test(reason)) return null;
+  return { kind: 'github-issue-pointer', role: 'public-build-issue-sync-root', label: parsed.browserTitle || parsed.title || repository, url: `https://github.com/${repository}/issues/1`, source: baseUrl || 'tiinex.build.json' };
+}
+
+function publicBuildIdentityUrlFor(target) {
+  try {
+    if (!target || isLikelyConfigUrl(target)) return '';
+    if (!/^https?:$/i.test(target.protocol || '')) return '';
+    return new URL('/tiinex.build.json', target.href).href;
+  } catch (_) { return ''; }
+}
+
+function successFromMarkdown({ markdown, configUrl, target, parseWorkspaceConfig, diagnostics }) {
+  const config = parseWorkspaceConfig(markdown);
+  const entrypoint = firstWorkspaceEntrypoint(config);
+  return { ok: true, targetUrl: target.href, configUrl, markdown, config, entrypoint, diagnostics };
+}
+
+function successFromHostedViewerSource({ source = {}, configUrl, target, diagnostics }) {
+  const entrypoint = {
+    name: source.label || source.repository || 'Hosted Tiinex source',
+    label: source.label || source.repository || 'Hosted Tiinex source',
+    sourceKind: source.sourceKind || 'github-tree',
+    repository: source.repository || source.repo || '',
+    ref: source.ref || '',
+    rootPath: source.rootPath || '.topics',
+    repoFilesDiscovery: source.repoFilesDiscovery || 'on',
+    issueDiscovery: source.issueDiscovery || 'off',
+    hostedRepoMirrorBaseUrls: source.hostedRepoMirrorBaseUrls || [],
+    hostedIssueSnapshotBaseUrls: source.hostedIssueSnapshotBaseUrls || []
+  };
+  return {
+    ok: true,
+    targetUrl: target.href,
+    configUrl,
+    markdown: '',
+    config: {
+      source: { kind: 'hosted-viewer-source', path: configUrl },
+      viewerIdentity: { browserTitle: source.label || source.repository || 'Hosted Tiinex source' },
+      workspaceDiscovery: [],
+      workspaceEntrypoints: [entrypoint],
+      repositoryMirrors: [],
+      repositoryTransports: [],
+      help: []
+    },
+    entrypoint,
+    diagnostics
+  };
+}
+
+async function resolveWorkspaceBootstrapCandidate(candidate = {}, options = {}) {
+  const fetchImpl = options.fetchImpl;
+  const target = options.target;
+  const parseWorkspaceConfig = options.parseWorkspaceConfig;
+  const diagnostics = options.diagnostics || {};
+  const kind = String(candidate.kind || '').toLowerCase();
+  if (kind === 'github-issue-pointer') {
+    const pointer = await resolveGithubIssueWorkspacePointer(candidate.url, { fetchImpl, target, diagnostics });
+    if (!pointer.ok) return pointer;
+    if (pointer.markdown) return successFromMarkdown({ markdown: pointer.markdown, configUrl: pointer.configUrl, target, parseWorkspaceConfig, diagnostics: Object.assign({}, diagnostics, { selectedConvention: 'github-issue-embedded-workspace' }) });
+    return await resolveWorkspaceBootstrapCandidate({ kind: 'workspace-url', url: pointer.workspaceUrl, role: candidate.role, source: pointer.source || candidate.source }, options);
+  }
+  const raw = candidate.path || candidate.url;
+  if (!raw) return failure('Empty Tiinex runtime workspace candidate.', { diagnostics });
+  const href = toFetchableWorkspaceUrl(new URL(raw, target.href).href);
+  const fetched = await tryFetchText(fetchImpl, href, 'text/markdown,text/plain,application/json,*/*');
+  if (!fetched.ok || !looksLikeWorkspaceConfig(fetched.text)) return failure(`Runtime workspace candidate was unavailable: ${href}`, { diagnostics, configUrl: href });
+  return successFromMarkdown({ markdown: fetched.text, configUrl: href, target, parseWorkspaceConfig, diagnostics: Object.assign({}, diagnostics, { selectedConvention: kind || 'runtime-workspace' }) });
+}
+
+async function resolveGithubIssueWorkspacePointer(candidateUrl = '', options = {}) {
+  const fetchImpl = options.fetchImpl;
+  const target = options.target;
+  const spec = parseGithubIssueSpec(candidateUrl);
+  if (!spec) return failure(`Workspace pointer is not a GitHub issue URL: ${candidateUrl}`, { diagnostics: options.diagnostics });
+
+  const hostedBody = await tryFetchHostedIssuePointerBody(spec, { fetchImpl, target });
+  if (hostedBody.ok) {
+    const resolved = workspacePointerMarkdownResult(hostedBody.text, hostedBody.url || spec.issueUrl);
+    if (resolved.ok) return resolved;
+  }
+
+  const apiUrl = `https://api.github.com/repos/${spec.repo}/issues/${spec.number}`;
+  const fetched = await tryFetchText(fetchImpl, apiUrl, 'application/vnd.github+json,application/json,*/*');
+  if (!fetched.ok) return failure(`GitHub workspace pointer could not be read: ${spec.issueUrl}`, { diagnostics: options.diagnostics, configUrl: spec.issueUrl });
+  try {
+    const issue = JSON.parse(fetched.text || '{}');
+    const body = String(issue.body || '');
+    const resolved = workspacePointerMarkdownResult(body, issue.html_url || spec.issueUrl);
+    if (resolved.ok) return resolved;
+  } catch (_) {}
+  return failure(`GitHub issue ${spec.repo}#${spec.number} did not declare a workspace URL or embed workspace markdown.`, { diagnostics: options.diagnostics, configUrl: spec.issueUrl });
+}
+
+async function tryFetchHostedIssuePointerBody(spec = {}, options = {}) {
+  const fetchImpl = options.fetchImpl;
+  const target = options.target;
+  if (!target) return { ok: false };
+  const candidates = [
+    `/issues/github.com/${spec.repo}/issues/${spec.number}/issue.md`,
+    `/issues/github.com/${spec.owner}/${spec.name}/issues/${spec.number}/issue.md`
+  ].map((path) => new URL(path, target.origin).href);
+  for (const href of [...new Set(candidates)]) {
+    const fetched = await tryFetchText(fetchImpl, href, 'text/markdown,text/plain,*/*');
+    if (fetched.ok && fetched.text) return { ok: true, text: fetched.text, url: href };
+  }
+  return { ok: false };
+}
+
+function workspacePointerMarkdownResult(markdown = '', baseUrl = '') {
+  const embedded = extractEmbeddedWorkspaceMarkdowns(markdown, baseUrl).find((item) => looksLikeWorkspaceConfig(item.markdown || ''));
+  if (embedded) return { ok: true, markdown: embedded.markdown, configUrl: `${baseUrl || 'github-issue'}#embedded-workspace`, source: baseUrl };
+  if (looksLikeWorkspaceConfig(markdown)) return { ok: true, markdown: String(markdown || '').trim(), configUrl: `${baseUrl || 'github-issue'}#workspace-markdown`, source: baseUrl };
+  const workspaceUrl = workspaceUrlFromPointerMarkdown(markdown, baseUrl);
+  if (workspaceUrl) return { ok: true, workspaceUrl, source: baseUrl, configUrl: workspaceUrl };
+  return failure('Workspace pointer did not declare a workspace URL.');
+}
+
+
+function firstWorkspaceEntrypoint(config = {}) {
+  return Array.isArray(config.workspaceEntrypoints) ? config.workspaceEntrypoints.find(workspaceEntrypointApplies) || null : null;
+}
+
+function githubRepositoryFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+    if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+  } catch (_) {}
+  const match = String(value || '').trim().match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:\.git)?$/u);
+  return match ? `${match[1]}/${match[2]}` : '';
+}
+
+function failure(message, extra = {}) {
+  return Object.assign({ ok: false, message }, extra);
+}

package/src/app/tiinexAppStartupSource.js

@@ -0,0 +1,79 @@
+import { fetchTiinexAppConfigSource, resolveTiinexRuntimeWorkspaceCandidate, tiinexAppConfigSourceToStartupPlan } from './tiinexAppConfigSource.js';
+import { normalizeWorkspaceBootstrapCandidate } from './tiinexHostedWorkspaceConventions.js';
+
+export function tiinexAppStartupRequestContext(options = {}) {
+  const locationLike = options.locationLike || globalThis.location || { href: '', search: '' };
+  let params;
+  try { params = new URLSearchParams(locationLike.search || new URL(locationLike.href || '', 'http://localhost/').search || ''); } catch (_) { params = new URLSearchParams(''); }
+  const pointer = params.get('workspacePointer') || params.get('issueWorkspace') || params.get('viewerWorkspacePointer') || params.get('workspaceIssue') || '';
+  const workspace = params.get('viewerWorkspace') || params.get('workspace') || params.get('viewerConfig') || params.get('config') || params.get('identity') || '';
+  return Object.freeze({ explicitQueryRequested: Boolean(pointer || workspace), pointer, workspace });
+}
+
+export function tiinexAppStartupCandidates(options = {}) {
+  const locationLike = options.locationLike || globalThis.location || { href: '', search: '' };
+  const hostInput = options.hostWorkspace !== undefined
+    ? options.hostWorkspace
+    : (options.windowObj?.TiinexWorkspace || options.windowObj?.tiinexWorkspace || options.windowObj?.TIINEX_WORKSPACE || globalThis.TiinexWorkspace || globalThis.tiinexWorkspace || globalThis.TIINEX_WORKSPACE || {});
+  const host = typeof hostInput === 'string' ? { defaultWorkspace: hostInput } : (hostInput && typeof hostInput === 'object' ? hostInput : {});
+  const candidates = [];
+  const add = (input, defaults = {}) => {
+    const normalized = normalizeWorkspaceBootstrapCandidate(input, defaults);
+    if (normalized) candidates.push(normalized);
+  };
+  const requestContext = tiinexAppStartupRequestContext({ locationLike });
+  if (requestContext.pointer) add({ kind: 'github-issue-pointer', url: requestContext.pointer }, { role: 'query-primary', label: 'Query workspace pointer', source: 'query' });
+  if (requestContext.workspace) add({ kind: 'workspace-url', url: requestContext.workspace }, { role: 'query-workspace', label: 'Query workspace', source: 'query' });
+  if (Array.isArray(host.candidates)) host.candidates.forEach((candidate, index) => add(candidate, { role: `runtime-${index + 1}`, source: 'window.TiinexWorkspace.candidates' }));
+  if (host.pointer) add(host.pointer, { kind: 'github-issue-pointer', role: 'runtime-pointer', label: 'Runtime workspace pointer', source: 'window.TiinexWorkspace.pointer' });
+  if (Array.isArray(host.pointers)) host.pointers.forEach((value, index) => add(value, { kind: 'github-issue-pointer', role: `runtime-pointer-${index + 1}`, source: 'window.TiinexWorkspace.pointers' }));
+  for (const key of ['defaultWorkspace', 'workspace', 'viewerWorkspace']) if (host[key]) add({ kind: 'workspace-url', url: host[key] }, { role: `runtime-${key}`, label: key, source: `window.TiinexWorkspace.${key}` });
+  if (host.fallbackWorkspace) add({ kind: 'workspace-url', url: host.fallbackWorkspace }, { role: 'runtime-fallback', label: 'Runtime fallback workspace', source: 'window.TiinexWorkspace.fallbackWorkspace' });
+  if (Array.isArray(host.fallbacks)) host.fallbacks.forEach((value, index) => add(value, { kind: 'workspace-url', role: `runtime-fallback-${index + 1}`, source: 'window.TiinexWorkspace.fallbacks' }));
+  const seen = new Set();
+  return candidates.filter((candidate) => {
+    const key = `${candidate.kind}\n${candidate.url || ''}\n${candidate.path || ''}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export async function resolveTiinexAppStartupGithubInput(targetUrl = '', options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const parseWorkspaceConfig = options.parseWorkspaceConfig || ((markdown) => ({ workspaceEntrypoints: [] }));
+  const startupCandidates = tiinexAppStartupCandidates(options);
+  const requestContext = tiinexAppStartupRequestContext(options);
+  const diagnostics = { startupCandidates: startupCandidates.map(compactCandidate), attempts: [], explicitQueryRequested: requestContext.explicitQueryRequested };
+  for (const candidate of startupCandidates) {
+    const attempt = Object.assign(compactCandidate(candidate), { ok: false });
+    diagnostics.attempts.push(attempt);
+    const resolved = await resolveTiinexRuntimeWorkspaceCandidate(candidate, { fetchImpl, parseWorkspaceConfig, targetUrl, locationLike: options.locationLike, diagnostics });
+    if (!resolved?.ok) { attempt.error = resolved?.message || resolved?.error || 'unavailable'; continue; }
+    attempt.ok = true;
+    return mapStartupResult(resolved, 'explicit-runtime-config', diagnostics, requestContext);
+  }
+  const hosted = await fetchTiinexAppConfigSource(targetUrl, { fetchImpl, parseWorkspaceConfig, baseUrl: options.baseUrl });
+  if (!hosted?.ok) return Object.assign({}, hosted || { ok: false, message: 'No hosted Tiinex startup config was found.' }, { startupClass: 'unresolved', explicitQueryRequested: requestContext.explicitQueryRequested, diagnostics: Object.assign({}, hosted?.diagnostics || {}, diagnostics) });
+  const convention = String(hosted.diagnostics?.selectedConvention || '').toLowerCase();
+  const startupClass = /embedded-default-workspace|convention-path/.test(convention) ? 'packaged-fallback-config' : 'hosted-config';
+  return mapStartupResult(hosted, startupClass, diagnostics, requestContext);
+}
+
+function mapStartupResult(result = {}, startupClass = '', diagnostics = {}, requestContext = {}) {
+  const mapped = tiinexAppConfigSourceToStartupPlan(result);
+  if (!mapped.ok) return Object.assign({}, mapped, { startupClass, explicitQueryRequested: Boolean(requestContext.explicitQueryRequested), diagnostics: result.diagnostics, configUrl: result.configUrl });
+  return Object.assign({}, mapped, {
+    startupClass,
+    explicitQueryRequested: Boolean(requestContext.explicitQueryRequested),
+    markdown: result.markdown || '',
+    config: result.config || {},
+    configUrl: result.configUrl || '',
+    targetUrl: result.targetUrl || '',
+    diagnostics: Object.assign({}, result.diagnostics || {}, diagnostics, { selectedConvention: result.diagnostics?.selectedConvention || '' })
+  });
+}
+
+function compactCandidate(candidate = {}) {
+  return { kind: candidate.kind || '', role: candidate.role || '', source: candidate.source || '', url: candidate.url || '', path: candidate.path || '' };
+}