@tiinex/app 0.1.1

package/src/app/localMaterialCommand.js

@@ -0,0 +1,124 @@
+import { collectLocalFilesFromDataTransfer, materializeLocalMarkdownFiles } from '../adapters/local/local.adapter.js';
+import { applyLocalAdapterResultToWorkspace } from '../workspaces/workspace.import.js';
+import { assertCanonicalWorkspaceRuntimeState } from '../workspaces/workspace.runtimeCanonical.js';
+import { durableLocalMutationDecision, DurableLocalMutationOperation } from './durableLocalMutationPolicy.js';
+import { applyOperationalHandoffPackageToWorkspace, tryReadOperationalHandoffPackage } from './handoffPackageImportCommand.js';
+import { fileToArchiveDecodedEntries } from '@tiinex/core/adapters/archive/archive.adapter.js';
+
+export async function runLocalMaterialImportCommand(input = {}) {
+  const lifecycle = input.lifecycle;
+  const state = input.state;
+  const options = input.options || {};
+  const authority = durableLocalMutationDecision(input.persistenceOwnership, DurableLocalMutationOperation.localMaterialIntake);
+  if (!authority.ok) return { ok: false, error: authority.error, state, notice: authority.notice, authority };
+  if (!lifecycle) return { ok: false, error: 'lifecycle.missing', state, notice: 'Could not add selected material.' };
+  const fileList = input.fileList || [];
+  const collectFiles = input.collectFiles || collectLocalFilesFromDataTransfer;
+  const materialize = input.materialize || materializeLocalMarkdownFiles;
+  const apply = input.apply || applyLocalAdapterResultToWorkspace;
+  const files = options.fromDataTransfer ? await collectFiles(fileList) : Array.from(fileList || []).filter(Boolean);
+  if (!files.length && !input.adapterResult) return { ok: false, error: 'local.files.empty', state, notice: 'No files selected.', files: [] };
+
+  let adapterResult = input.adapterResult || null;
+  let predecodedArchive = null;
+  const singleZip = files.length === 1 && /\.zip$/i.test(String(files[0]?.name || files[0]?.relativePath || files[0]?.tiinexRelativePath || ''));
+  if (!adapterResult && options.handoffPackage !== false && singleZip) {
+    try {
+      predecodedArchive = await fileToArchiveDecodedEntries(files[0], options);
+    } catch (error) {
+      return { ok: false, error: 'local.materialize.failed', state, notice: 'Could not read local files or archives.', exception: error, files };
+    }
+  }
+  if (!adapterResult && options.handoffPackage !== false) {
+    const handoff = await tryReadOperationalHandoffPackage(files, predecodedArchive ? { ...options, predecodedArchive } : options);
+    if (handoff.detected) {
+      if (!handoff.ok) return { ok: false, error: handoff.error || 'handoff-package.invalid', state, notice: handoff.notice || 'Claimed Handoff package failed validation.', files, handoffPackage: handoff };
+      const appliedHandoff = applyOperationalHandoffPackageToWorkspace({ lifecycle, state, handoff, options });
+      if (!appliedHandoff?.ok) return { ok: false, error: appliedHandoff?.error || 'handoff-package.apply-failed', state, notice: appliedHandoff?.notice || 'Could not import Handoff package.', files, handoffPackage: handoff, applied: appliedHandoff };
+      const canonicality = assertCanonicalWorkspaceRuntimeState(appliedHandoff.state, 'handoff-package-import');
+      if (!canonicality.ok) return { ok: false, error: 'workspace.runtime-candidate-model-leak', state, notice: 'Imported Handoff package could not be normalized safely.', files, handoffPackage: handoff, applied: appliedHandoff, canonicality };
+      return { ok: true, state: appliedHandoff.state, notice: appliedHandoff.notice, files, handoffPackage: handoff, applied: appliedHandoff, materialCount: (appliedHandoff.adapterResult?.records?.length || 0) + (appliedHandoff.adapterResult?.assets?.length || 0) + (appliedHandoff.adapterResult?.workspaceEntries?.length || 0), workspaceId: appliedHandoff.workspaceId || '' };
+    }
+  }
+  if (!adapterResult) {
+    try {
+      adapterResult = await materialize(files, { ...options, ...(predecodedArchive ? { predecodedArchive } : {}), sourceMode: options.sourceMode || 'manual-files' });
+    } catch (error) {
+      return { ok: false, error: 'local.materialize.failed', state, notice: 'Could not read local files or archives.', exception: error, files };
+    }
+  }
+
+  const materialCount = localMaterialCount(adapterResult);
+  if (!materialCount) {
+    const skipped = (adapterResult?.warnings?.length || 0) + (adapterResult?.errors?.length || 0);
+    return {
+      ok: false,
+      error: skipped ? 'local.material.empty-with-findings' : 'local.material.empty',
+      state,
+      notice: skipped ? 'No readable Markdown, workspace, asset, or zip material was imported.' : 'No files selected.',
+      files,
+      adapterResult,
+      materialCount
+    };
+  }
+
+  let applied;
+  try {
+    applied = apply(lifecycle, state, input.workspaceId || '', adapterResult, options);
+  } catch (error) {
+    return { ok: false, error: 'local.apply.failed', state, notice: 'Could not materialize selected zip/files into the workspace.', exception: error, files, adapterResult, materialCount };
+  }
+
+  const changed = Boolean(applied?.addedRecords || applied?.addedAssets || applied?.workspaceOpened || applied?.workspaceEntries);
+  if (applied?.error === 'import.conflict.requires-resolution') {
+    return { ok: false, error: applied.error, state, notice: 'Incoming material overlaps this workspace.', conflicts: applied.conflicts || [], files, adapterResult, applied, materialCount };
+  }
+  if (applied?.error === 'import.cancelled') {
+    return { ok: false, error: applied.error, cancelled: true, state, notice: 'Import cancelled.', conflicts: applied.conflicts || [], files, adapterResult, applied, materialCount };
+  }
+  if (!applied?.ok && applied?.state === state && !changed) {
+    return { ok: false, error: applied?.error || 'local.apply.noop', state, notice: 'Could not add selected material.', files, adapterResult, applied, materialCount };
+  }
+  const nextState = applied?.state || state;
+  const canonicality = assertCanonicalWorkspaceRuntimeState(nextState, 'local-import');
+  if (!canonicality.ok) return { ok: false, error: 'workspace.runtime-candidate-model-leak', state, notice: 'Imported workspace material could not be normalized safely.', files, adapterResult, applied, materialCount, canonicality };
+  return {
+    ok: applied?.ok !== false || changed,
+    state: nextState,
+    notice: applied?.summary?.message || 'Import completed.',
+    files,
+    adapterResult,
+    applied,
+    materialCount,
+    summary: applied?.summary || null,
+    workspaceId: applied?.workspaceId || input.workspaceId || ''
+  };
+}
+
+export function localMaterialCount(adapterResult = {}) {
+  return (adapterResult.records?.length || 0) + (adapterResult.assets?.length || 0) + (adapterResult.workspaceEntries?.length || 0);
+}
+
+
+export function looksLikePastedTraceMarkdown(text = '') {
+  const body = String(text || '');
+  if (!body.trim()) return false;
+  if (/^#\s+Continuity Context\s*$/m.test(body)) return true;
+  return /^\s*Current Schema\s*:/mi.test(body) && /^#\s+Continuity Integrity\s*$/m.test(body);
+}
+
+export function makePastedTraceFile(text = '', options = {}) {
+  const body = String(text || '');
+  if (!looksLikePastedTraceMarkdown(body)) return null;
+  const stamp = (typeof options.clock === 'function' ? options.clock() : new Date().toISOString()).replace(/[:.]/g, '-');
+  const name = `pasted-trace-${stamp}.trace.md`;
+  const bytes = new TextEncoder().encode(body);
+  if (typeof File !== 'undefined') return new File([body], name, { type: 'text/markdown' });
+  return {
+    name,
+    size: bytes.byteLength,
+    type: 'text/markdown',
+    async text() { return body; },
+    async arrayBuffer() { return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength); }
+  };
+}

package/src/app/nodeGraphVerse.case.mjs

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { applyArtifactGraphLod, ArtifactGraphScope, buildArtifactGraph, graphNodeId, projectArtifactGraphScope } from '../graph/artifactGraph.model.js';
+import { deterministicArtifactGraphLayout, prepareArtifactGraphProjection, scheduleArtifactGraphProjection } from '../graph/artifactGraph.project.js';
+import { activeWorkspaceViewFor } from './workspaceMulticolumn.js';
+import { stateWithWorkspaceViewPatchAndFocus, workspaceVerseNavigationPatch } from './workspaceScopedInteraction.js';
+
+const root = record('root', 'Root', '.topics/root.trace.md');
+const child = record('child', 'Child', '.topics/branch/child.trace.md', '.topics/root.trace.md');
+const sibling = record('sibling', 'Sibling', '.topics/branch/sibling.trace.md');
+const alpha = { id: 'alpha', title: 'Alpha', records: [root], assets: [] };
+const beta = { id: 'beta', title: 'Beta', records: [child, sibling], assets: [] };
+
+// The model reuses declared lineage truth and namespaces workspace identity without merging workspace authority.
+const model = buildArtifactGraph([alpha, beta]);
+assert.equal(model.schema, 'tiinex.artifact-graph.model.v1');
+assert.equal(model.nodes.length, 3);
+assert(model.nodes.some((node) => node.id === graphNodeId('alpha', root.id)));
+const crossParent = model.edges.find((edge) => edge.kind === 'parent' && edge.to === graphNodeId('beta', child.id));
+assert(crossParent, 'declared Parent edge should remain present');
+assert.equal(crossParent.from, graphNodeId('alpha', root.id), 'unique exact Parent path may project across workspace boundaries');
+assert.equal(crossParent.crossWorkspace, true);
+assert.match(crossParent.method, /^exact-cross-workspace-/);
+
+const workspaceProjection = projectArtifactGraphScope(model, { workspaceId: 'beta', scope: ArtifactGraphScope.workspace });
+assert.deepEqual(workspaceProjection.nodes.map((node) => node.workspaceId), ['beta', 'beta']);
+assert.equal(workspaceProjection.edges.some((edge) => edge.crossWorkspace), false, 'single-workspace scope does not silently import another boundary');
+const focusProjection = projectArtifactGraphScope(model, { workspaceId: 'beta', scope: ArtifactGraphScope.focus, selectedRecordId: child.id });
+assert(focusProjection.nodes.some((node) => node.id === graphNodeId('alpha', root.id)), 'focus neighborhood can intentionally traverse an exact cross-workspace relation');
+const multiverse = projectArtifactGraphScope(model, { workspaceId: 'beta', scope: ArtifactGraphScope.multi });
+assert.equal(multiverse.workspaces.length, 2);
+assert.equal(multiverse.edges.filter((edge) => edge.crossWorkspace).length, 1);
+
+// Ambiguous exact cross-workspace targets remain unresolved rather than fabricating a relation.
+const alphaDuplicate = { id: 'alpha-duplicate', title: 'Alpha duplicate', records: [record('root-duplicate', 'Root duplicate', '.topics/root.trace.md')], assets: [] };
+const ambiguous = buildArtifactGraph([alpha, alphaDuplicate, beta]);
+const ambiguousParent = ambiguous.edges.find((edge) => edge.kind === 'parent' && edge.to === graphNodeId('beta', child.id));
+assert.equal(ambiguousParent.from, '');
+assert(ambiguous.findings.some((finding) => finding.code === 'artifactGraph.crossWorkspaceParent.ambiguous'));
+
+// LOD is explicit, deterministic, boundary-aware and reports omitted material.
+const many = {
+  id: 'many', title: 'Many', records: Array.from({ length: 80 }, (_, index) => {
+    const suffix = String(index).padStart(3, '0');
+    const parentSuffix = String(index - 1).padStart(3, '0');
+    return record(`n-${suffix}`, `Node ${index}`, `.topics/n-${suffix}.trace.md`, index ? `.topics/n-${parentSuffix}.trace.md` : '');
+  })
+};
+const manyGraph = projectArtifactGraphScope(buildArtifactGraph([many]), { workspaceId: 'many', scope: ArtifactGraphScope.workspace });
+const lod = applyArtifactGraphLod(manyGraph, { maxNodes: 20 });
+assert.equal(lod.nodes.length, 20);
+assert.equal(lod.lod.truncated, true);
+assert.equal(lod.lod.omittedNodes, 60);
+assert.equal(lod.edges.length, 19, 'LOD should preserve a connected local topology for a linear lineage instead of returning disconnected ranked ties');
+
+// Layout is stable for the same semantic graph regardless of input order and never claims authority.
+const layoutA = deterministicArtifactGraphLayout(multiverse);
+const layoutB = deterministicArtifactGraphLayout({ ...multiverse, nodes: multiverse.nodes.slice().reverse(), edges: multiverse.edges.slice().reverse() });
+assert.deepEqual(layoutA.positions, layoutB.positions);
+assert.equal(layoutA.authority, 'derived-projection-only');
+assert.equal(layoutA.deterministic, true);
+assert.equal(layoutA.bands.length, 2);
+
+const prepared = prepareArtifactGraphProjection({ workspaces: [alpha, beta], workspaceId: 'beta', scope: ArtifactGraphScope.multi, maxNodes: 200 });
+assert.equal(prepared.layout.schema, 'tiinex.artifact-graph.layout.v1');
+assert.equal(prepared.graph.lod.truncated, false);
+
+
+let workerPosted = false;
+let workerTerminated = false;
+await new Promise((resolve, reject) => {
+  const listeners = {};
+  const fakeWorker = {
+    addEventListener(type, handler) { listeners[type] = handler; },
+    postMessage(message) { workerPosted = true; queueMicrotask(() => listeners.message?.({ data: { id: message.id, ok: true, projection: { workerPrepared: true } } })); },
+    terminate() { workerTerminated = true; }
+  };
+  scheduleArtifactGraphProjection({ workspaces: [alpha], workspaceId: 'alpha' }, { workerFactory: () => fakeWorker, onReady: (value) => { try { assert.equal(value.workerPrepared, true); resolve(); } catch (error) { reject(error); } }, onError: reject });
+});
+assert.equal(workerPosted, true, 'browser scheduler should prefer off-thread preparation when a Worker is available');
+assert.equal(workerTerminated, true, 'one-shot graph worker should terminate after returning its projection');
+
+// Graph navigation preserves selected artifact focus while Feed/Tree return still clears lineage-only state.
+const view = { universe: 'column', workspaceVerse: 'lineage', selectedRecordId: child.id, lineageReturnVerse: 'tree', query: 'child' };
+const state = { activeWorkspaceId: beta.id, workspaces: [beta], view, workspaceViews: { [beta.id]: view } };
+const graphState = stateWithWorkspaceViewPatchAndFocus(state, beta.id, workspaceVerseNavigationPatch('graph'), 1280);
+assert.equal(graphState.view.workspaceVerse, 'graph');
+assert.equal(graphState.view.selectedRecordId, child.id);
+assert.equal(activeWorkspaceViewFor(graphState, beta.id).workspaceVerse, 'graph');
+const feedState = stateWithWorkspaceViewPatchAndFocus(graphState, beta.id, workspaceVerseNavigationPatch('feed'), 1280);
+assert.equal(feedState.view.selectedRecordId, '');
+
+// Product wiring keeps graph code out of first paint and opens the canonical workspace artifact on selection.
+const workspaceViewSource = fs.readFileSync(new URL('../schemas/workspace/workspace.views.jsx', import.meta.url), 'utf8');
+const graphViewSource = fs.readFileSync(new URL('../schemas/workspace/workspace.graph.views.jsx', import.meta.url), 'utf8');
+const toolbarSource = fs.readFileSync(new URL('../schemas/workspace/workspace.chrome.views.jsx', import.meta.url), 'utf8');
+assert.ok(workspaceViewSource.includes("React.lazy(() => import('./workspace.graph.views.jsx')"));
+assert.ok(graphViewSource.includes('scheduleArtifactGraphProjection'));
+assert.ok(graphViewSource.includes('onOpenRecord?.(node.workspaceId, node.recordId)'));
+assert.ok(graphViewSource.includes('Multi-Verse'));
+assert.ok(toolbarSource.includes('GRAPH ORIENTATION'));
+assert.ok(toolbarSource.includes('aria-label="Discovery view"'), 'existing Feed/Tree discovery UI shape remains intact');
+
+console.log('✓ Node Graph Verse projection invariants passed');
+
+function record(id, title, path, trace = '') {
+  const parent = trace ? `- Parent\n  - Parent Schema: [tiinex.topic.v1](tiinex.topic.v1.schema.md)\n  - Trace: [Parent](${trace})\n` : '';
+  const markdown = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](tiinex.root.v1.schema.md)\n${parent}- Current\n  - Current Schema: [tiinex.topic.v1](tiinex.topic.v1.schema.md)\n  - Created At: 2026-09-03 12:00:00\n  - Summary: ${title}\n\n---\n\n# ${title}\n\n${title} body.\n\n---\n\n# Continuity Integrity\n\n- local-test\n  - Towards: self\n  - Value: ${id}-self\n`;
+  return Object.assign(createRecordFromMarkdown(markdown, { path, sourceMode: 'local-test' }), { id });
+}

package/src/app/persistenceOwnership.js

@@ -0,0 +1,92 @@
+export const PersistenceRouteOwner = Object.freeze({
+  semanticState: 'semantic-state',
+  publicTarget: 'public-target',
+  clean: 'clean'
+});
+
+export const TIINEX_HISTORY_AUTHORITY_KEY = '__tiinexPersistenceAuthority';
+export const TIINEX_HISTORY_AUTHORITY_SCHEMA = 'tiinex.history.persistenceAuthority.v1';
+
+export const DurableLocalAuthority = Object.freeze({
+  normal: 'normal',
+  isolatedPreexistingRecovery: 'isolated-preexisting-recovery'
+});
+
+export function createPersistenceOwnershipPolicy(initialRouteKind = PersistenceRouteOwner.clean, options = {}) {
+  let routeKind = normalizeRouteKind(initialRouteKind);
+  let durableLocalAuthority = normalizeDurableLocalAuthority(
+    options.durableLocalAuthority,
+    routeKind === PersistenceRouteOwner.publicTarget ? DurableLocalAuthority.isolatedPreexistingRecovery : DurableLocalAuthority.normal
+  );
+
+  function setRouteKind(nextKind = PersistenceRouteOwner.clean) {
+    routeKind = normalizeRouteKind(nextKind);
+    return routeKind;
+  }
+
+  function setDurableLocalAuthority(nextAuthority = DurableLocalAuthority.normal) {
+    durableLocalAuthority = normalizeDurableLocalAuthority(nextAuthority);
+    return durableLocalAuthority;
+  }
+
+  function restoreHistoryEntry({ routeKind: nextRouteKind = PersistenceRouteOwner.clean, durableLocalAuthority: nextDurableAuthority = DurableLocalAuthority.normal } = {}) {
+    routeKind = normalizeRouteKind(nextRouteKind);
+    durableLocalAuthority = normalizeDurableLocalAuthority(nextDurableAuthority, routeKind === PersistenceRouteOwner.publicTarget ? DurableLocalAuthority.isolatedPreexistingRecovery : DurableLocalAuthority.normal);
+    return report();
+  }
+
+  function beginSemanticNavigation(requestedMode = 'push') {
+    const firstExitFromPublicTarget = routeKind === PersistenceRouteOwner.publicTarget;
+    routeKind = PersistenceRouteOwner.semanticState;
+    return Object.freeze({
+      firstExitFromPublicTarget,
+      mode: firstExitFromPublicTarget ? 'push' : normalizeWriteMode(requestedMode),
+      routeKind,
+      durableLocalAuthority
+    });
+  }
+
+  function writePolicy() {
+    const out = { routeKind, durableLocalAuthority };
+    if (routeKind === PersistenceRouteOwner.publicTarget) out.preserveUrl = true;
+    if (durableLocalAuthority === DurableLocalAuthority.isolatedPreexistingRecovery) out.durableLocalPolicy = 'preserve-existing';
+    out.historyStatePatch = historyStatePatch(durableLocalAuthority);
+    return Object.freeze(out);
+  }
+
+  function report() { return Object.freeze({ routeKind, durableLocalAuthority }); }
+
+  return Object.freeze({ setRouteKind, setDurableLocalAuthority, restoreHistoryEntry, beginSemanticNavigation, writePolicy, report });
+}
+
+export function persistenceWriteEnvForOwnership(ownership = null, base = {}) {
+  const policy = ownership?.writePolicy?.() || {};
+  return Object.assign({}, base || {}, policy);
+}
+
+export function isolatedDurableLocalAuthority(ownership = null) {
+  return ownership?.report?.().durableLocalAuthority === DurableLocalAuthority.isolatedPreexistingRecovery;
+}
+
+function historyStatePatch(durableLocalAuthority) {
+  return {
+    [TIINEX_HISTORY_AUTHORITY_KEY]: durableLocalAuthority === DurableLocalAuthority.isolatedPreexistingRecovery
+      ? Object.freeze({ schema: TIINEX_HISTORY_AUTHORITY_SCHEMA, durableLocalAuthority: DurableLocalAuthority.isolatedPreexistingRecovery })
+      : null
+  };
+}
+
+function normalizeRouteKind(value = '') {
+  const kind = String(value || '').trim();
+  if (kind === PersistenceRouteOwner.semanticState || kind === PersistenceRouteOwner.publicTarget) return kind;
+  return PersistenceRouteOwner.clean;
+}
+
+function normalizeDurableLocalAuthority(value = '', fallback = DurableLocalAuthority.normal) {
+  const authority = String(value || '').trim();
+  if (authority === DurableLocalAuthority.isolatedPreexistingRecovery) return authority;
+  if (authority === DurableLocalAuthority.normal) return authority;
+  return fallback;
+}
+
+function normalizeWriteMode(value = '') { return value === 'push' ? 'push' : 'replace'; }

package/src/app/productStateBoundary.js

@@ -0,0 +1,7 @@
+import { stateWithWorkspacePresentationPruned } from './workspaceMulticolumn.js';
+
+export function canonicalProductState(state = {}, _persistence = null, boundary = 'product-runtime') {
+  const violation = (state?.workspaces || []).find((workspace) => workspace && Object.prototype.hasOwnProperty.call(workspace, 'workspaceMergeCandidates'));
+  if (violation) throw new Error(`workspace.runtime-candidate-leak:${boundary}:${violation.id || 'workspace'}`);
+  return stateWithWorkspacePresentationPruned(state);
+}

package/src/app/providers/AppProviders.js

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

package/src/app/providers/LocaleProvider.js

@@ -0,0 +1 @@
+export function LocaleProvider(locale) { return { locale }; }

package/src/app/providers/SchemaRegistryProvider.js

@@ -0,0 +1 @@
+export function SchemaRegistryProvider(registry) { return registry; }

package/src/app/providers/WorkspaceProvider.js

@@ -0,0 +1 @@
+export function WorkspaceProvider(workspace) { return workspace; }

package/src/app/publicTarget.js

@@ -0,0 +1,251 @@
+import { parseGithubIssueSnapshotTarget } from '../adapters/github/github.issueSnapshot.js';
+import { normalizeWorkspaceMemberIdentity, singleWorkspaceMemberBinding } from '../workspaces/workspace.memberIdentity.js';
+
+export const PUBLIC_TARGET_SCHEMA = 'tiinex.publicTarget.v1';
+
+export const PublicTargetRestoreCapability = Object.freeze({
+  restorable: 'restorable',
+  unsupported: 'unsupported',
+  invalid: 'invalid'
+});
+
+export function classifyRouteLocation(locationLike = {}) {
+  const hash = String(locationLike?.hash || '').trim();
+  if (!hash) return Object.freeze({ kind: 'clean', hash: '' });
+  if (/^#state=/i.test(hash)) return Object.freeze({ kind: 'semantic-state', hash });
+  const target = parsePublicTargetHash(hash);
+  if (target) return Object.freeze({ kind: 'public-target', hash, target });
+  return Object.freeze({ kind: 'unsupported-hash', hash });
+}
+
+export function parsePublicTargetHash(hashValue = '') {
+  const raw = String(hashValue || '').replace(/^#/, '').trim();
+  if (!raw) return null;
+  const decoded = safeDecode(raw);
+  if (/^(?:state|view)=/i.test(decoded)) return null;
+  const splitter = decoded.indexOf('|');
+  const adapterHint = splitter > 0 ? normalizePublicAdapter(decoded.slice(0, splitter)) : '';
+  const payload = splitter > 0 ? decoded.slice(splitter + 1) : decoded;
+  if (adapterHint === 'workspace.member') return parseWorkspaceMemberRoutePayload(payload);
+  const externalTarget = safeDecode(payload);
+  return publicTargetFromExternalUrl(externalTarget, adapterHint);
+}
+
+export function publicTargetFromExternalUrl(value = '', adapterHint = '') {
+  const externalTarget = String(value || '').trim();
+  if (!/^https?:\/\//i.test(externalTarget)) return null;
+  const hinted = normalizePublicAdapter(adapterHint);
+  const githubIssue = parseGithubIssueSnapshotTarget(externalTarget);
+  if (githubIssue.ok && (!hinted || hinted === 'github.issue' || hinted === 'github.discussion')) {
+    return freezeTarget({
+      adapterId: 'github',
+      targetKind: githubIssue.commentId ? 'github.issue.comment' : (githubIssue.kind === 'discussion' ? 'github.discussion' : 'github.issue'),
+      externalTarget: githubIssue.canonicalUrl,
+      repository: githubIssue.repository,
+      issueNumber: githubIssue.number,
+      commentId: githubIssue.commentId || ''
+    });
+  }
+  const githubFile = parseGithubFileTarget(externalTarget);
+  if (githubFile && (!hinted || hinted === 'github.file' || hinted === 'workspace')) {
+    return freezeTarget(Object.assign({}, githubFile, {
+      targetKind: hinted === 'workspace'
+        ? 'workspace'
+        : (hinted === 'github.file' ? 'github.file' : (/\.workspace\.md$/i.test(githubFile.path) ? 'workspace' : 'github.file'))
+    }));
+  }
+  let url;
+  try { url = new URL(externalTarget); } catch (_) { return null; }
+  const path = url.pathname || '';
+  const targetKind = hinted === 'workspace'
+    ? 'workspace'
+    : (hinted === 'web.markdown'
+      ? 'web.markdown'
+      : (/\.workspace\.md$/i.test(path) ? 'workspace' : (/\.(?:md|markdown|txt)$/i.test(path) ? 'web.markdown' : 'web.url')));
+  return freezeTarget({ adapterId: 'web', targetKind, externalTarget: url.href });
+}
+
+export function artifactPublicTargetFromRecord(record = {}) {
+  for (const value of recordPublicTargetValues(record)) {
+    const parsed = artifactPublicTargetFromExternalUrl(value);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+export function publicTargetFromRecord(record = {}) {
+  for (const value of recordPublicTargetValues(record)) {
+    const parsed = publicTargetFromExternalUrl(value, isWorkspaceArtifact(record) ? 'workspace' : '');
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+export function buildPublicTargetHash(target = {}) {
+  const normalized = normalizePublicTarget(target);
+  if (!normalized) return '';
+  const adapter = routeAdapterForTarget(normalized);
+  if (normalized.targetKind === 'workspace.member') {
+    const payload = JSON.stringify({ target: normalized.externalTarget, memberKey: normalized.memberIdentity?.key || '' });
+    return `#${encodeURIComponent(`${adapter}|${payload}`)}`;
+  }
+  return `#${encodeURIComponent(`${adapter}|${normalized.externalTarget}`)}`;
+}
+
+export function buildPublicViewerTargetUrl(target = {}, publicViewerUrl = '') {
+  const hash = buildPublicTargetHash(target);
+  const base = safePublicViewerUrl(publicViewerUrl);
+  if (!hash || !base) return '';
+  const url = new URL(base);
+  url.hash = '';
+  return `${url.href}${hash}`;
+}
+
+export function normalizePublicTarget(target = {}) {
+  if (target?.schema === PUBLIC_TARGET_SCHEMA && /^https?:\/\//i.test(String(target.externalTarget || ''))) {
+    if (target.targetKind === 'workspace.member' && !normalizeWorkspaceMemberIdentity(target.memberIdentity)) return null;
+    return freezeTarget(target);
+  }
+  return publicTargetFromExternalUrl(target?.externalTarget || target?.url || '', target?.targetKind || target?.adapter || target?.adapterId || '');
+}
+
+export function publicTargetFromWorkspaceMemberBinding(binding = null) {
+  const descriptor = binding?.descriptorTarget;
+  const memberIdentity = normalizeWorkspaceMemberIdentity(binding?.memberIdentity);
+  if (!descriptor || !memberIdentity) return null;
+  const target = publicTargetFromExternalUrl(descriptor.externalTarget || '', 'workspace');
+  return target ? freezeTarget(Object.assign({}, target, { targetKind: 'workspace.member', memberIdentity })) : null;
+}
+
+export function publicTargetFromWorkspace(workspace = {}) {
+  const binding = singleWorkspaceMemberBinding(workspace);
+  return binding ? publicTargetFromWorkspaceMemberBinding(binding) : null;
+}
+
+
+export function publicTargetRestoreCapability(target = {}) {
+  const normalized = normalizePublicTarget(target);
+  if (!normalized) return PublicTargetRestoreCapability.invalid;
+  const kind = normalized.targetKind;
+  if (kind === 'web.url') return PublicTargetRestoreCapability.unsupported;
+  if (['github.issue', 'github.issue.comment', 'github.discussion'].includes(kind)) {
+    return normalized.adapterId === 'github' && normalized.repository && normalized.issueNumber
+      ? PublicTargetRestoreCapability.restorable
+      : PublicTargetRestoreCapability.invalid;
+  }
+  if (kind === 'github.file') {
+    return normalized.adapterId === 'github' && normalized.repository && normalized.path
+      ? PublicTargetRestoreCapability.restorable
+      : PublicTargetRestoreCapability.invalid;
+  }
+  if (kind === 'web.markdown') {
+    return normalized.adapterId === 'web'
+      ? PublicTargetRestoreCapability.restorable
+      : PublicTargetRestoreCapability.invalid;
+  }
+  if (kind === 'workspace' || kind === 'workspace.member') {
+    if (normalized.adapterId === 'github') {
+      return normalized.repository && normalized.path
+        ? PublicTargetRestoreCapability.restorable
+        : PublicTargetRestoreCapability.invalid;
+    }
+    return normalized.adapterId === 'web'
+      ? PublicTargetRestoreCapability.restorable
+      : PublicTargetRestoreCapability.invalid;
+  }
+  return PublicTargetRestoreCapability.unsupported;
+}
+
+function artifactPublicTargetFromExternalUrl(value = '') {
+  const externalTarget = String(value || '').trim();
+  if (!/^https?:\/\//i.test(externalTarget)) return null;
+  const githubIssue = parseGithubIssueSnapshotTarget(externalTarget);
+  if (githubIssue.ok) return publicTargetFromExternalUrl(externalTarget);
+  if (parseGithubFileTarget(externalTarget)) return publicTargetFromExternalUrl(externalTarget, 'github.file');
+  let url;
+  try { url = new URL(externalTarget); } catch (_) { return null; }
+  if (/\.(?:md|markdown|txt)$/i.test(url.pathname || '')) return publicTargetFromExternalUrl(externalTarget, 'web.markdown');
+  return publicTargetFromExternalUrl(externalTarget);
+}
+
+function recordPublicTargetValues(record = {}) {
+  return [
+    record?.sourceTarget?.inputTarget,
+    record?.sourceTarget?.sourceUrl,
+    record?.sourceTarget?.rawUrl,
+    record?.snapshot?.target?.canonicalUrl,
+    record?.snapshot?.sourceUrl,
+    record?.source?.url
+  ].map((value) => String(value || '').trim()).filter(Boolean);
+}
+
+function freezeTarget(input = {}) {
+  const memberIdentity = input.targetKind === 'workspace.member' ? normalizeWorkspaceMemberIdentity(input.memberIdentity) : null;
+  return Object.freeze({
+    schema: PUBLIC_TARGET_SCHEMA,
+    adapterId: String(input.adapterId || '').trim(),
+    targetKind: String(input.targetKind || '').trim(),
+    externalTarget: String(input.externalTarget || '').trim(),
+    repository: String(input.repository || '').trim(),
+    ref: String(input.ref || '').trim(),
+    path: String(input.path || '').trim(),
+    issueNumber: Number(input.issueNumber || 0),
+    commentId: String(input.commentId || '').trim(),
+    ...(memberIdentity ? { memberIdentity } : {})
+  });
+}
+
+function parseWorkspaceMemberRoutePayload(payload = '') {
+  let parsed = null;
+  try { parsed = JSON.parse(String(payload || '')); } catch (_) { return null; }
+  const descriptor = publicTargetFromExternalUrl(parsed?.target || '', 'workspace');
+  const memberIdentity = normalizeWorkspaceMemberIdentity({ key: parsed?.memberKey || '' });
+  if (!descriptor || !memberIdentity) return null;
+  return freezeTarget(Object.assign({}, descriptor, { targetKind: 'workspace.member', memberIdentity }));
+}
+
+function parseGithubFileTarget(value = '') {
+  let url;
+  try { url = new URL(value); } catch (_) { return null; }
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (url.hostname === 'github.com' && parts.length >= 5 && parts[2] === 'blob') {
+    const [owner, repo, , ref, ...pathParts] = parts;
+    if (!owner || !repo || !ref || !pathParts.length) return null;
+    return { adapterId: 'github', externalTarget: url.href, repository: `${owner}/${repo}`, ref, path: pathParts.join('/') };
+  }
+  if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 4) {
+    const [owner, repo, ref, ...pathParts] = parts;
+    if (!owner || !repo || !ref || !pathParts.length) return null;
+    return { adapterId: 'github', externalTarget: url.href, repository: `${owner}/${repo}`, ref, path: pathParts.join('/') };
+  }
+  return null;
+}
+
+function normalizePublicAdapter(value = '') {
+  const key = String(value || '').trim().toLowerCase().replace(/:/g, '.');
+  if (['issue', 'github-issue', 'github.issue'].includes(key)) return 'github.issue';
+  if (['discussion', 'github-discussion', 'github.discussion'].includes(key)) return 'github.discussion';
+  if (['github.file', 'github.raw', 'github.blob', 'github.raw-file'].includes(key)) return 'github.file';
+  if (['workspace.member', 'tiinex.workspace.member', 'workspace-member'].includes(key)) return 'workspace.member';
+  if (['workspace', 'tiinex.workspace', 'web.workspace', 'workspace.md'].includes(key)) return 'workspace';
+  if (['web.markdown', 'web.md', 'markdown', 'web.file'].includes(key)) return 'web.markdown';
+  if (['web.url', 'web', 'url'].includes(key)) return 'web.url';
+  return key;
+}
+
+function routeAdapterForTarget(target = {}) {
+  if (target.targetKind === 'workspace.member') return 'workspace.member';
+  if (target.targetKind === 'workspace') return 'workspace';
+  if (target.targetKind === 'github.issue' || target.targetKind === 'github.issue.comment') return 'github.issue';
+  if (target.targetKind === 'github.discussion') return 'github.discussion';
+  if (target.targetKind === 'github.file') return 'github.file';
+  if (target.targetKind === 'web.markdown') return 'web.markdown';
+  return 'web.url';
+}
+
+function isWorkspaceArtifact(record = {}) {
+  return Boolean(record?.workspaceArtifactRole?.openEligible) || /\.workspace\.md$/i.test(String(record?.path || record?.sourceTarget?.sourceArtifactPath || ''));
+}
+
+function safeDecode(value = '') { try { return decodeURIComponent(String(value || '')); } catch (_) { return String(value || ''); } }
+function safePublicViewerUrl(value = '') { try { const url = new URL(String(value || '').trim()); return /^https?:$/.test(url.protocol) ? url.href : ''; } catch (_) { return ''; } }