@tiinex/app 0.1.1

package/src/react/VerseHost.jsx

@@ -0,0 +1,29 @@
+import React, { useEffect, useState } from 'react';
+import { loadVerse } from '../verses/hostRegistry.js';
+import { useVerseHostContext } from './applicationDataContext.jsx';
+
+export function VerseHost({ verseId, registry, host = {}, fallback = null, onLoadState = null }) {
+  const context = useVerseHostContext(host);
+  const [state, setState] = useState(() => ({ status: 'loading', id: verseId, module: null, definition: registry?.get?.(verseId) || null }));
+  useEffect(() => {
+    let active = true;
+    setState({ status: 'loading', id: verseId, module: null, definition: registry?.get?.(verseId) || null });
+    loadVerse(registry, verseId).then((next) => {
+      if (!active) return;
+      setState(next);
+      onLoadState?.(next);
+    });
+    return () => { active = false; };
+  }, [registry, verseId, onLoadState]);
+
+  if (state.id !== verseId || state.status !== 'ready') return typeof fallback === 'function' ? fallback(state) : fallback;
+  const Component = state.module?.default || state.module?.Verse || state.module?.PlaythingsVerse;
+  if (typeof Component !== 'function') return typeof fallback === 'function' ? fallback({ ...state, status: 'invalid-module' }) : fallback;
+  return React.createElement(Component, Object.freeze({
+    applicationData: context.applicationData,
+    getPlaythingsStoryRecords: context.getPlaythingsStoryRecords,
+    resolveCompanions: context.resolveCompanions,
+    host: context.host,
+    verse: state.definition
+  }));
+}

package/src/react/applicationDataContext.jsx

@@ -0,0 +1,30 @@
+import React, { createContext, useContext, useMemo, useSyncExternalStore } from 'react';
+
+const TiinexApplicationRuntimeContext = createContext(null);
+
+export function TiinexApplicationRuntimeProvider({ runtime, children }) {
+  if (!runtime?.data?.subscribe || !runtime?.data?.getSnapshot) throw new TypeError('A Tiinex application runtime is required.');
+  return React.createElement(TiinexApplicationRuntimeContext.Provider, { value: runtime }, children);
+}
+
+export function useTiinexApplicationRuntime() {
+  const runtime = useContext(TiinexApplicationRuntimeContext);
+  if (!runtime) throw new Error('TiinexApplicationRuntimeProvider is missing.');
+  return runtime;
+}
+
+export function useTiinexApplicationData() {
+  const runtime = useTiinexApplicationRuntime();
+  return useSyncExternalStore(runtime.data.subscribe, runtime.data.getSnapshot, runtime.data.getServerSnapshot);
+}
+
+export function useVerseHostContext(extraHost = {}) {
+  const runtime = useTiinexApplicationRuntime();
+  const applicationData = useTiinexApplicationData();
+  return useMemo(() => Object.freeze({
+    applicationData,
+    getPlaythingsStoryRecords: runtime.getPlaythingsStoryRecords,
+    resolveCompanions: runtime.resolveCompanions,
+    host: Object.freeze({ ...extraHost })
+  }), [runtime, applicationData, extraHost]);
+}

package/src/react.js

@@ -0,0 +1,2 @@
+export { TiinexApplicationRuntimeProvider, useTiinexApplicationRuntime, useTiinexApplicationData, useVerseHostContext } from './react/applicationDataContext.jsx';
+export { VerseHost } from './react/VerseHost.jsx';

package/src/readers/modes/audit.reader.js

@@ -0,0 +1 @@
+export const auditReader = Object.freeze({ mode: 'audit' });

package/src/readers/modes/detail.reader.js

@@ -0,0 +1 @@
+export const detailReader = Object.freeze({ mode: 'detail' });

package/src/readers/modes/handover.reader.js

@@ -0,0 +1 @@
+export const handoverReader = Object.freeze({ mode: 'handover' });

package/src/readers/modes/mobile.reader.js

@@ -0,0 +1 @@
+export const mobileReader = Object.freeze({ mode: 'mobile' });

package/src/readers/modes/print.reader.js

@@ -0,0 +1 @@
+export const printReader = Object.freeze({ mode: 'print' });

package/src/readers/modes/scan.reader.js

@@ -0,0 +1 @@
+export const scanReader = Object.freeze({ mode: 'scan' });

package/src/readers/reader.model.js

@@ -0,0 +1 @@
+export const ReaderMode = Object.freeze({ scan: 'scan', detail: 'detail', audit: 'audit', handover: 'handover', mobile: 'mobile', print: 'print' });

package/src/readers/reader.resolve.js

@@ -0,0 +1,2 @@
+export const defaultReaderModes = Object.freeze(['scan','detail','audit','handover','mobile','print']);
+export function resolveReaderMode(mode = 'scan') { return defaultReaderModes.includes(mode) ? mode : 'scan'; }

package/src/reingest/reingest.plan.case.mjs

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict';
+import { buildReingestPlan } from '@tiinex/core/reingest/reingest.plan.js';
+
+const validDraftMarkdown = `# Continuity Context
+
+- Envelope Schema: [tiinex.root.v1](tiinex.root.v1.schema.md)
+- Current
+  - Current Schema: [tiinex.topic.v1](tiinex.topic.v1.schema.md)
+  - Created At: 2026-07-21T00:00:00.000Z
+  - Summary: Draft
+  - Status: draft/local
+
+---
+
+# Draft
+
+# Continuity Integrity
+
+- Draft Local Integrity
+  - Method: browser-local-draft
+  - Value: pending-publication-or-export
+`;
+
+const readySource = buildReingestPlan({
+  id: 'w-source',
+  title: 'Source workspace',
+  sources: [{ id: 'github:tiinex/docs', adapterId: 'github', repo: 'Tiinex/docs', ref: 'main' }],
+  records: [{ id: 'source-1', title: 'Source', path: 'topics/source.md', markdown: validDraftMarkdown, source: { adapterId: 'github', repo: 'Tiinex/docs', ref: 'main', materializedCommit: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' }, sourceTarget: { surface: 'repoFiles', targetKind: 'github-repo-file', sourceArtifactPath: 'topics/source.md', materializedCommit: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' } }],
+  assets: []
+});
+assert.equal(readySource.schema, 'tiinex.reingest.plan.v1');
+assert.equal(readySource.status, 'ready');
+assert.equal(readySource.counts.pinnedSourceTargets, 1);
+assert.equal(readySource.sourceTargets[0].status, 'pinned');
+
+const degraded = buildReingestPlan({
+  id: 'w-degraded',
+  title: 'Degraded workspace',
+  sources: [{ id: 'github:tiinex/docs', adapterId: 'github', repo: 'Tiinex/docs', ref: '' }],
+  records: [
+    { id: 'draft-ready', title: 'Draft', path: 'drafts/draft.md', markdown: validDraftMarkdown, source: { adapterId: 'local' }, sourceMode: 'local-transition' },
+    { id: 'source-unpinned', title: 'Source unpinned', path: 'topics/source.md', markdown: validDraftMarkdown, source: { adapterId: 'github', repo: 'Tiinex/docs', ref: '' } }
+  ],
+  assets: [{ id: 'asset-large', path: 'assets/large.bin', previewState: 'omitted-large', source: { adapterId: 'local' } }],
+  workspaceMergeCandidates: [{ id: 'wc', path: 'workspace.workspace.md' }]
+});
+assert.equal(degraded.status, 'degraded');
+assert.equal(degraded.counts.localDraftTargets, 1);
+assert.equal(degraded.counts.degradedSourceTargets, 1);
+assert.equal(degraded.counts.metadataOnlyAssets, 1);
+assert.equal(degraded.counts.workspaceCandidates, 1);
+assert.ok(degraded.findings.some((finding) => finding.code === 'reingest.github.ref-unpinned'));
+assert.ok(degraded.findings.some((finding) => finding.code === 'reingest.asset.metadata-only'));
+assert.ok(degraded.findings.some((finding) => finding.code === 'reingest.workspace-candidate.explicit-open-merge-required'));
+
+const blocked = buildReingestPlan({
+  id: 'w-blocked',
+  title: 'Blocked workspace',
+  sources: [{ id: 'local', adapterId: 'local', repo: 'Tiinex/docs' }],
+  records: [{ id: 'leak', title: 'Leaked local', path: 'leak.md', markdown: validDraftMarkdown, source: { adapterId: 'local', repo: 'Tiinex/docs' } }]
+});
+assert.equal(blocked.status, 'blocked');
+assert.ok(blocked.findings.some((finding) => finding.code === 'record.local.github-provenance-leak'));
+
+console.log('reingest.plan: ok');

package/src/runtime.js

@@ -0,0 +1,54 @@
+import { schemaRegistry } from '@tiinex/core/schemas/registry.js';
+import { projectSchemaAncestry } from '@tiinex/core';
+import { createCompanionAccess } from './data/companionAccess.js';
+import { companionProviderFromWorkspace, projectApplicationData, resolveCompanionResources, toPlaythingsStoryRecords } from '@tiinex/core';
+import { createApplicationDataStore } from './data/applicationDataStore.js';
+import { createVerseRegistry } from './verses/hostRegistry.js';
+
+export function createTiinexApplicationRuntime(options = {}) {
+  const store = createApplicationDataStore();
+  const access = createCompanionAccess(options);
+  const schemas = Object.freeze((options.schemaDeclarations || schemaRegistry.modules.map(m => ({id:m.id,parentSchemaId:m.parentSchemaId,checksum:m.binding?.checksum?.value || '',basis:'installed-schema-module-declaration'}))).map(s => Object.freeze({...s})));
+  const verses = options.verses?.get ? options.verses : createVerseRegistry(options.verses || []);
+  let configuredProviders = Object.freeze([...(options.companionProviders || [])]);
+  let workspaceProviders = Object.freeze([]);
+  let workspaceProviderFindings = Object.freeze([]);
+
+  const api = {
+    data: store,
+    verses,
+    setWorkspaces(workspaces = []) {
+      access.setWorkspaces(workspaces);
+      const projected = Object.freeze({ ...projectApplicationData({ workspaces }), schemas });
+      const derived = workspaces.map((workspace) => companionProviderFromWorkspace(workspace));
+      workspaceProviders = Object.freeze(derived.map((item) => item.provider));
+      workspaceProviderFindings = Object.freeze(derived.flatMap((item) => item.findings || []));
+      store.replace(projected);
+      return projected;
+    },
+    setCompanionProviders(providers = []) {
+      configuredProviders = Object.freeze([...(Array.isArray(providers) ? providers : [])]);
+      return api.getCompanionProviders();
+    },
+    getCompanionProviders() { return Object.freeze([...workspaceProviders, ...configuredProviders]); },
+    getCompanionProviderFindings() { return workspaceProviderFindings; },
+    schemaAncestry: (schemaId) => projectSchemaAncestry(schemaId, schemas),
+    resolveCompanions(query) {
+      const matches = store.getSnapshot().records.filter(r => r.workspaceId === query.owner?.workspaceId && r.path === query.owner?.artifactPath);
+      const id = query.owner?.schemaId || (matches.length === 1 ? matches[0].schemaId : '');
+      const ancestry = projectSchemaAncestry(id, schemas);
+      if (['ambiguous','cycle'].includes(ancestry.status)) return Object.freeze({status:'blocked',resources:Object.freeze([]),findings:Object.freeze([{code:'companion.schema-ancestry.'+ancestry.status}])});
+      return resolveCompanionResources({ providers: api.getCompanionProviders(), query: { ...query, schemaLineage: query.schemaLineage || ancestry.lineage } });
+    },
+    getPlaythingsStoryRecords() { return toPlaythingsStoryRecords(store.getSnapshot()); },
+    async readCompanion(resource, options) {
+      const entries=api.getCompanionProviders().flatMap(p=>p.resources || []);
+      const matches=entries.filter(r=>r.providerId===resource?.providerId && r.id===resource?.id && r.path===resource?.path && r.sha256===resource?.sha256);
+      if(matches.length!==1) throw new Error('Companion selection is stale, ambiguous or unregistered.');
+      return access.read(matches[0],options);
+    },
+    getSnapshot() { return store.getSnapshot(); }
+  };
+  if (Array.isArray(options.workspaces)) api.setWorkspaces(options.workspaces);
+  return Object.freeze(api);
+}

package/src/schemas/README.md

@@ -0,0 +1,99 @@
+# Schema Companion Contract
+
+This directory contains schema companions that the viewer can resolve through the schema registry. Tiinex/docs is the canonical core origin, not the only allowed origin. The file tree is an implementation detail; durable schema identity comes from each companion's schema id and binding metadata.
+
+This README describes the companion contract. It intentionally does **not** list every installed schema, because schema inventories belong in the registry/manifest and would become stale here.
+
+## Principle
+
+Schema-specific meaning stays with the schema companion.
+
+Generic engines may live outside `src/schemas`, but they must not absorb Topic/Evidence/etc. rules:
+
+- `src/validation/` owns validation orchestration, finding normalization, and i18n lookup APIs.
+- `src/integrity/` owns reusable checksum/canonicalization/integrity engines.
+- `src/schemas/<schema>/` owns schema-specific validation, presentation, capabilities, findings, i18n resources, and future transitions.
+
+## Minimal companion
+
+A schema builder should be able to generate a useful companion with only:
+
+```text
+<schema-id>.schema.md
+<schema-id>.schema.json
+<schema-id>.schema.js
+```
+
+Example:
+
+```text
+tiinex.topic.v1.schema.md
+tiinex.topic.v1.schema.json
+tiinex.topic.v1.schema.js
+```
+
+The schema id, including version suffix, is propagated into companion filenames. Short labels such as `Topic` are display labels only.
+
+## Optional companion roles
+
+Optional files are added only when the schema diverges from Root or needs additional behavior:
+
+```text
+<schema-id>.validate.js
+<schema-id>.presenter.js
+<schema-id>.capabilities.js
+<schema-id>.findings.js
+<schema-id>.<locale>.i18n.json
+<schema-id>.transitions.js
+```
+
+Current convention keeps the folder flat. Locale files use Tiinex-style naming:
+
+```text
+<schema-id>.en.i18n.json
+<schema-id>.sv.i18n.json
+```
+
+## Validation
+
+Validation is composed by `src/validation/validateArtifact.js`:
+
+```text
+parse
+→ Root validation
+→ generic integrity validation
+→ exact schema validation, if available
+→ normalized findings + validation truth
+```
+
+Child validators do not import or call Root validation manually. They only emit schema-specific finding codes.
+
+## Findings and i18n
+
+Validators emit stable finding codes, not user-facing prose as the source of truth.
+
+```text
+validator emits: topic.title.missing
+findings says: severity/fixability/messageKey
+i18n says: localized human text
+```
+
+A finding companion is useful when a schema owns custom finding codes. A schema that only relies on Root findings does not need its own findings file.
+
+Human-readable messages resolve through `<schema-id>.<locale>.i18n.json`. Missing locale keys should fall back explicitly; they must not create new validation semantics.
+
+## Presenters
+
+`<schema-id>.presenter.js` is the schema-specific projection seam. Feed, Tree, Lineage, and other workspace surfaces may share the same presenter unless the schema truly needs a divergent projection.
+
+Do not create surface-specific wrapper files just to set `surface: 'feed'` or similar. Add a surface-specific presenter only when it has real schema-specific behavior and is wired through the schema module/registry.
+
+## Transitions and forms
+
+Transitions are passive until the transition milestone. Root may define the safety contract for transitions, but concrete transition/product behavior must be explicit and schema/capability-owned.
+
+Form companions are not part of the active Root milestone. They should be introduced with the transition/artifact-creation milestone, not shipped as inert scaffold.
+
+## Workspace module
+
+`src/schemas/workspace/` is the viewer-local workspace schema companion. It is allowed to contain React workspace surfaces because the workspace schema is the viewer entrypoint. Core schema companions should stay React-free.