@volter/editor-react 0.5.210 → 0.5.212

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@volter/editor-react",
+  "publisher": "volter",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
-  "version": "0.5.210",
+  "version": "0.5.212",
+  "engines": {
+    "vscode": "*"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -31,19 +35,26 @@
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json"
   },
-  "volter": {
-    "contributions": [
-      "./contributions/component-contracts.service.ts"
-    ],
-    "serving": "./dist-node/serving.mjs"
+  "contributes": {
+    "volter": {
+      "serving": [
+        "./dist-node/serving.mjs"
+      ],
+      "services": [
+        {
+          "module": "./contributions/component-contracts.service.ts",
+          "sourceAnalyzer": "component-contracts"
+        }
+      ]
+    }
   },
   "dependencies": {
-    "@volter/sdk": "0.5.210",
-    "@volter/project": "0.5.210",
+    "@volter/sdk": "0.5.212",
+    "@volter/project": "0.5.212",
     "typescript": "5.9.3"
   },
   "peerDependencies": {
-    "vite": "^6.4.3"
+    "vite": "^6.4.3 || ^7.0.0 || ^8.0.0"
   },
   "devDependencies": {
     "esbuild": "0.25.12"

package/serving/component-prop-worker.ts

@@ -1,22 +1,6 @@
-/**
- * TypeScript declared-prop analysis, isolated from the Vite HTTP thread.
- *
- * `ComponentPropResolver` builds a full ts.Program on its first query. That is
- * deliberately real TypeScript semantic analysis, but it is CPU-bound and
- * takes seconds on a cold project. Running it from `setImmediate` does not
- * make it asynchronous: it still freezes the one Node event loop serving the
- * editor. This worker keeps one incremental resolver per project and returns
- * only the ecosystem-native prop descriptions the OID index already carries.
- *
- * The `.ts` extensions below are LOAD-BEARING, not a style slip. `new
- * Worker(new URL('./server/component-prop-worker.ts', …))` hands this file to
- * Node directly: tsx's resolver hooks do not reach a worker thread, so the
- * module is executed by Node's own type stripping, whose ESM resolver demands
- * an explicit extension. Dropping them resolves under tsc and then dies at
- * runtime with ERR_MODULE_NOT_FOUND the first time the editor asks for
- * declared props. `tsconfig.server.json` sets `allowImportingTsExtensions`
- * for exactly this reason.
- */
+/** Resolve declared TypeScript props away from the Vite HTTP event loop.
+ * Keep one incremental ComponentPropResolver per project and return specs for
+ * each requested definition or callsite. */
 import { parentPort } from 'node:worker_threads';
 import { ComponentPropResolver } from '../src/source/component-prop-types';
 import type { ComponentPropSpec } from '@volter/sdk/source-authoring';

package/serving/index.ts

@@ -1,21 +1,33 @@
 /**
- * `@volter/editor-react`'s server half (`package.json#volter.serving`, the project-serving door in
+ * `@volter/editor-react`'s server half (`package.json#contributes.volter.serving`, the project-serving door in
  * `@volter/sdk/session/project-serving`): the JSX identity stamp and the `/__ui-source/*`
  * authoring routes over a project's React and React Three Fiber source, and the source answers
- * the kit's region decision, validation and Content index ask of a JSX lane.
+ * the kit's region decision, validation and Content index ask of a JSX lane. It registers the `dom`
+ * substrate, the `dom` surface's default row.
  */
 
 import type { ProjectServingModule } from '@volter/sdk/session/project-serving';
-import { analyzeR3fComponentContracts, builtinR3fContractsForSource, sourceDialectEvidence } from '../src/source/oid-transform';
-import { r3fAuthoringDiagnostics } from '../src/source/r3f-project-contracts';
+import { analyzeR3fComponentContracts, builtinR3fContractsForSource } from '../src/source/oid-transform';
+import { r3fSourceDiagnostics } from './source-diagnostics';
 import { uiOidPlugin } from './ui-oid-plugin';
 
 export const servingPlugins: ProjectServingModule['servingPlugins'] = (services) => [uiOidPlugin(services)];
 
-export { sourceDialectEvidence };
-
-export const sourceDiagnostics: ProjectServingModule['sourceDiagnostics'] = (code, file, options) =>
-  r3fAuthoringDiagnostics(code, file, options);
+export const sourceDiagnostics: ProjectServingModule['sourceDiagnostics'] = (code, file, decision) =>
+  r3fSourceDiagnostics(code, file, decision);
 
 export const componentContracts: ProjectServingModule['componentContracts'] = (source, path) =>
   analyzeR3fComponentContracts(source, path, builtinR3fContractsForSource(source, path));
+
+/**
+ * The `dom` substrate: the `dom` surface's default row, authored in the `jsx` dialect through the
+ * source-prop and structural anchors.
+ */
+export const substrates: ProjectServingModule['substrates'] = [
+  {
+    substrate: 'dom',
+    surface: 'dom',
+    dialects: ['jsx'],
+    default: { dialect: 'jsx', anchors: ['source-prop', 'source-structure'] },
+  },
+];

package/serving/source-diagnostics.ts

@@ -0,0 +1,311 @@
+/**
+ * The authoring diagnostics this integration answers through the serving door's `sourceDiagnostics`
+ * (`@volter/sdk/session/project-serving`): what a module's own source says against the kit's region
+ * decision for it. The kit decides which region owns a file and stamps from that alone; these diagnostics
+ * read the file's dialect evidence (`sourceDialectEvidence`) and say where it disagrees with the decision,
+ * at the volume its consequence deserves.
+ *
+ *   - `OID001`: the file is inside the project, but no region reaches it and none declares it, so its
+ *     attribute is the `data-oid` default. Graded by what its own host elements are.
+ *   - `OID003`: the file's rendered HOST ELEMENTS contradict the region that owns it. The region still
+ *     decides the attribute, and the disagreement is said out loud so the author can fix the declaration
+ *     (or the file).
+ *   - `OID004`: the file renders BOTH R3F-only and DOM-only intrinsics. A per-FILE attribute cannot
+ *     serve both dialects, so no answer is correct; this is reported, never guessed around.
+ *   - `R3F002`-`R3F005`: the R3F authoring conventions (`r3f-project-contracts.ts`), for a module the kit
+ *     validates on save that a region places on `stage`.
+ */
+
+import type { AuthoringDiagnostic } from '@volter/sdk/source-authoring';
+import type { SourceRegionDecision } from '@volter/sdk/session/project-serving';
+import { ADAPTER_MODULE_FILENAME } from '@volter/project/adapter/adapter-module';
+import { type SourceDialectEvidence, sourceDialectEvidence, sourceProvesR3f } from '../src/source/oid-transform';
+import { r3fAuthoringDiagnostics } from '../src/source/r3f-project-contracts';
+
+/** The label the kit prints these diagnostics under. */
+const SOURCE = 'R3F authoring';
+
+interface StampDiagnostic {
+  readonly code: string;
+  readonly message: string;
+}
+
+/** Portable CSF is a design-time document. A component-only story commonly
+ * renders `<Story />` or a provider decorator and is reached from no runtime
+ * root, but importing it from one or giving it a manifest root would be exactly
+ * the wrong repair. The preview lane qualifies its rendered output
+ * independently, while selectable nodes retain the OIDs stamped in the
+ * prefab/component source they came from. */
+function isPortableStoryModule(file: string): boolean {
+  return /\.stories\.[jt]sx?$/i.test(file);
+}
+
+function evidenceSummary(evidence: SourceDialectEvidence): string {
+  const parts: string[] = [];
+  if (evidence.reconcilerImport) parts.push('imports the R3F reconciler');
+  if (evidence.r3fOnlyTags.length > 0) {
+    parts.push(`renders R3F-only <${evidence.r3fOnlyTags.slice(0, 4).join('>, <')}>`);
+  }
+  if (evidence.domOnlyTags.length > 0) {
+    parts.push(`renders DOM-only <${evidence.domOnlyTags.slice(0, 4).join('>, <')}>`);
+  }
+  return parts.length > 0 ? parts.join('; ') : 'carries no dialect evidence of its own';
+}
+
+/** True for DOM-only host output. These files need no missing-region
+ * warning because the default data-oid stamp is correct. */
+function rendersOnlyDomHosts(evidence: SourceDialectEvidence): boolean {
+  return evidence.domOnlyTags.length > 0 && evidence.r3fOnlyTags.length === 0;
+}
+
+/** True for R3F-only host output. A DOM stamp would pierce a nonexistent
+ * object.data field, so diagnostics require the owning stage declaration. */
+function rendersOnlyR3fHosts(evidence: SourceDialectEvidence): boolean {
+  return evidence.r3fOnlyTags.length > 0 && evidence.domOnlyTags.length === 0;
+}
+
+/**
+ * THE FATAL DIRECTION of declared-vs-measured drift: a `dom`/`canvas` region
+ * owning a file whose host elements are THREE objects — see
+ * {@link rendersOnlyR3fHosts} for what `data-oid` does to one of those.
+ *
+ * Reported, and the region still stamps: which region owns a file is the project's
+ * to state, and the include glob is where it states it. `why` names how the
+ * non-`stage` answer came to be believed, so the diagnostic reads as one
+ * sentence.
+ */
+function r3fHostDriftDiagnostic(
+  absFile: string,
+  why: string,
+  evidence: SourceDialectEvidence,
+  rootsNote: string,
+): StampDiagnostic {
+  return {
+    code: 'OID003',
+    message:
+      `${absFile} ${why}, but the file itself ${evidenceSummary(evidence)} and renders no DOM ` +
+      'element at all — its host elements are THREE objects, and `data-oid` on one of those is ' +
+      'not a degraded stamp: react-three-fiber pierces the dash, writes `object.data` on the ' +
+      'first apply and THROWS on the next one (`R3F: Cannot set "data-oid"`), so this file will ' +
+      'break the running project, not merely fail to select. If it really is part of a ' +
+      `\`dom\`/\`canvas\` region, move its R3F elements out of it; otherwise give it a \`stage\` ` +
+      `root of its own, or declare it onto the \`stage\` surface with an \`include\` glob (or a ` +
+      `\`mounts\` entry, if this root mounts \`stage\` beside another surface) in ` +
+      `${ADAPTER_MODULE_FILENAME}. Roots considered: ${rootsNote}.`,
+  };
+}
+
+/** How the diagnostic names the way a `stage` surface came to be believed. */
+function whyOf(region: SourceRegionDecision['region']): string {
+  if (region.via === 'declared-include') {
+    return `is declared onto the \`${region.regionId}\` region's \`stage\` surface in ${ADAPTER_MODULE_FILENAME}`;
+  }
+  if (region.via === 'root-entry')
+    return 'is declared as a `stage` root entry in volter.project.json';
+  return 'is reached only from a `stage` root';
+}
+
+/** OID001's extra clause about what the defaulted file's own bytes say — the
+ *  consequence, graded. A file whose HOST elements are THREE objects gets the
+ *  `data-oid` default and will THROW inside fiber on the second apply (see
+ *  {@link rendersOnlyR3fHosts}), so its clause says so; a file that merely
+ *  IMPORTS the reconciler has nothing for a wrong stamp to land on and only
+ *  fails to select. */
+function unresolvableClause(evidence: SourceDialectEvidence): string {
+  if (rendersOnlyR3fHosts(evidence)) {
+    return (
+      ` — and this file ${evidenceSummary(evidence)}, so the \`data-oid\` default lands on THREE ` +
+      'objects: react-three-fiber pierces the dash, writes `object.data` on the first apply and ' +
+      'THROWS on the next one. Declaring this file is not optional cleanup — the running project ' +
+      'breaks without it'
+    );
+  }
+  return sourceProvesR3f(evidence)
+    ? ` — and this file ${evidenceSummary(evidence)}, so its selection will NOT resolve`
+    : '';
+}
+
+/** What the file's own source says against the region decision for it. */
+function stampDiagnostics(
+  absFile: string,
+  evidence: SourceDialectEvidence,
+  decision: SourceRegionDecision,
+): StampDiagnostic[] {
+  const { region, project } = decision;
+  const roots = project?.roots ?? '(none)';
+  const diagnostics: StampDiagnostic[] = [];
+
+  if (evidence.r3fOnlyTags.length > 0 && evidence.domOnlyTags.length > 0) {
+    diagnostics.push({
+      code: 'OID004',
+      message:
+        `${absFile} renders BOTH R3F-only (<${evidence.r3fOnlyTags.slice(0, 3).join('>, <')}>) ` +
+        `and DOM-only (<${evidence.domOnlyTags.slice(0, 3).join('>, <')}>) elements. The editor ` +
+        'stamps ONE source-id attribute per file (`userData-oid` for the R3F reconciler, ' +
+        '`data-oid` for react-dom), so selection can only resolve for one of the two dialects ' +
+        'in this file. Split the DOM part (e.g. the contents of a drei <Html>) into its own ' +
+        'module to make both halves selectable.',
+    });
+  }
+
+  if (region.surface !== undefined) {
+    // DRIFT, REPORTED AND NOT ACTED ON: a `stage` region owning a file whose
+    // HOST ELEMENTS are DOM elements. The region still stamps — it is the
+    // project's own statement about which surface this file renders on, and a
+    // stamp derived from the file's bytes instead would make the declaration
+    // untestable, and a wrong declaration would stay invisible. What
+    // the author sees is the disagreement itself, plus the two declarations
+    // that resolve it.
+    if (region.surface === 'stage' && rendersOnlyDomHosts(evidence)) {
+      diagnostics.push({
+        code: 'OID003',
+        message:
+          `${absFile} ${whyOf(region)}, but the file itself ${evidenceSummary(evidence)} and ` +
+          'renders no R3F element at all — its host elements are DOM elements, so the ' +
+          '`userData-oid` stamped from that region is an unrecognized React prop on every one of ' +
+          'them and selection resolves for neither dialect. This is the normal shape for ' +
+          'HUD/overlay modules that import `@react-three/fiber` only for `addEffect`/`useFrame`: ' +
+          `declare them onto this root's \`dom\` surface with a \`mounts\` entry in ` +
+          `${ADAPTER_MODULE_FILENAME}, or give them a \`dom\` root of their own in ` +
+          'volter.project.json. If this file really does author R3F content, render an R3F element ' +
+          `in it. Roots considered: ${roots}.`,
+      });
+    }
+    // DRIFT, REPORTED AND NOT ACTED ON — the FATAL direction: a non-`stage`
+    // region owning a file whose HOST ELEMENTS are THREE objects. The region
+    // still stamps, for the same reason it does above. What differs is the
+    // consequence, and the diagnostic says it (`r3fHostDriftDiagnostic`).
+    if (region.surface !== 'stage' && rendersOnlyR3fHosts(evidence)) {
+      diagnostics.push(
+        r3fHostDriftDiagnostic(
+          absFile,
+          `belongs to a \`${region.surface}\` region (${region.via})`,
+          evidence,
+          roots,
+        ),
+      );
+    }
+    // DRIFT, REPORTED AND NOT ACTED ON: a non-`stage` region reaching a file
+    // that IMPORTS the R3F reconciler but renders no host element of either
+    // dialect. Import reach is not render reach — a `dom` root CAN render an
+    // R3F `<Canvas>`, and its children are reached through the graph — so this
+    // is a real, nameable disagreement between the declaration and the source,
+    // with nothing in the file for a wrong stamp to land on.
+    if (
+      region.surface !== 'stage' &&
+      evidence.reconcilerImport &&
+      evidence.r3fOnlyTags.length === 0 &&
+      evidence.domOnlyTags.length === 0
+    ) {
+      diagnostics.push({
+        code: 'OID003',
+        message:
+          `${absFile} belongs to a \`${region.surface}\` region (${region.via}), but the file ` +
+          `itself ${evidenceSummary(evidence)} — import reach is not render reach (a ` +
+          `\`${region.surface}\` root can render an R3F <Canvas>). \`data-oid\` is stamped from ` +
+          'the region, so any R3F element here will not resolve to a selection. Give this file a ' +
+          `\`stage\` root of its own, or declare it onto the \`stage\` surface with an \`include\` ` +
+          `glob (or a \`mounts\` entry) in ${ADAPTER_MODULE_FILENAME}. Roots considered: ${roots}.`,
+      });
+    }
+    return diagnostics;
+  }
+
+  if (
+    region.ambiguity !== 'differing-surfaces' &&
+    project &&
+    // "No region reaches it" is only a FINDING at a stamp, where the served
+    // module graph was consulted; at a save it is just ignorance, and claiming
+    // it would warn about every non-entry file in the project.
+    decision.at === 'stamp' &&
+    // The noise gate — see `rendersOnlyDomHosts`: an unplaced file whose host
+    // elements are DOM already carries the attribute it needs, because the
+    // default IS `data-oid`.
+    !rendersOnlyDomHosts(evidence) &&
+    // The story exemption is a NOISE gate too, and it stops at the fatal case:
+    // an unplaced story whose own host elements are THREE objects takes the
+    // `data-oid` default onto them and throws inside fiber on the second mount
+    // (see `rendersOnlyR3fHosts`). Silence about a crash is not noise reduction.
+    (!isPortableStoryModule(absFile) || rendersOnlyR3fHosts(evidence))
+  ) {
+    diagnostics.push({
+      code: 'OID001',
+      message:
+        `${absFile} is inside the project at ${project.manifest} but ` +
+        'no region reaches it and none declares it, so the source-id attribute it carries is a ' +
+        `DEFAULT, not a decision${unresolvableClause(evidence)}. Import it from a region entry (directly or ` +
+        'transitively), give it a root, or declare it via a region `include` glob in ' +
+        `${ADAPTER_MODULE_FILENAME}. Roots considered: ${project.roots}.`,
+    });
+  }
+  return diagnostics;
+}
+
+/**
+ * The validation-time leftover the stamp diagnostics do not cover: a root entry
+ * that IMPORTS the reconciler while rendering no host element of EITHER
+ * dialect. A `dom`/`canvas` entry that imports fiber for `addEffect`/`useFrame`
+ * and renders DOM elements has no R3F element to fail to resolve; one that
+ * renders THREE objects is the fatal-direction drift, already reported.
+ */
+function entryConflict(
+  absFile: string,
+  evidence: SourceDialectEvidence,
+  decision: SourceRegionDecision,
+): StampDiagnostic | null {
+  const direct = decision.project?.entrySurface;
+  if (
+    direct === undefined ||
+    direct === 'stage' ||
+    !evidence.reconcilerImport ||
+    evidence.r3fOnlyTags.length > 0 ||
+    evidence.domOnlyTags.length > 0
+  ) {
+    return null;
+  }
+  return {
+    code: 'OID003',
+    message:
+      `${absFile} is declared as a \`${direct}\` root entry in volter.project.json, but the file ` +
+      `${evidenceSummary(evidence)}. The manifest wins (\`data-oid\` is stamped), so any R3F ` +
+      'element here will not resolve to a selection. Declare a `stage` root for the R3F part.',
+  };
+}
+
+/**
+ * The door's `sourceDiagnostics`. At a module's stamp (`decision.at === 'stamp'`), the
+ * diagnostics about the stamp. When the kit validates a saved module (`'save'`),
+ * the R3F authoring conventions for a module a region places on `stage`, then
+ * the stamp diagnostics the file's bytes and the manifest settle between them:
+ * `OID004` and `OID003`, plus the root-entry leftover.
+ */
+export function r3fSourceDiagnostics(
+  code: string,
+  file: string,
+  decision: SourceRegionDecision,
+): AuthoringDiagnostic[] {
+  const evidence = sourceDialectEvidence(code);
+  const labelled = (diagnostic: StampDiagnostic): AuthoringDiagnostic => ({
+    code: diagnostic.code,
+    message: diagnostic.message,
+    source: SOURCE,
+  });
+  if (decision.at === 'stamp') return stampDiagnostics(file, evidence, decision).map(labelled);
+  const conventions = r3fAuthoringDiagnostics(code, file, {
+    knownStageSurface: decision.region.surface === 'stage',
+  }).map(
+    (diagnostic): AuthoringDiagnostic => ({
+      code: diagnostic.code,
+      message: diagnostic.message,
+      line: diagnostic.line,
+      col: diagnostic.col,
+      source: SOURCE,
+    }),
+  );
+  const conflict = entryConflict(file, evidence, decision);
+  return [
+    ...conventions,
+    ...stampDiagnostics(file, evidence, decision).map(labelled),
+    ...(conflict ? [labelled(conflict)] : []),
+  ];
+}