@volter/editor-react 0.5.210 → 0.5.212

package/src/source/relative-import-specifier.ts

@@ -1,21 +1,6 @@
-/**
- * The relative import specifier a human would write from one module to
- * another — the ONE copy of the shared-prefix walk that existed five times
- * (owner-directed overlap audit, 2026-08-22): `R3fSourceAuthoringAdapter.
- * relativeModuleSpecifier`, `ReactRootAuthoringAdapter.relativeProjectModule`,
- * `pixi-source-write-target`'s `relativeProjectModule`, and the
- * `relativeSpecifier` locals in `plan-fork-component.ts` and
- * `plan-extract-component.ts`.
- *
- * Dependency-free on purpose (no `node:path`): two of the five consumers are
- * pure planner modules that must stay headlessly probeable, and a specifier is
- * a POSIX-slash artifact regardless of host platform.
- *
- * What stays at the call site, deliberately: resolving the two paths into the
- * SAME address space (project-relative vs absolute — both work, the walk eats
- * any shared prefix, but they must match). A source extension on the target is
- * stripped; an extension-less module id passes through unchanged.
- */
+/** Construct a relative import specifier from two paths in the same address
+ * space, using POSIX slashes and stripping the target source extension. No
+ * platform path API is needed, so browser and Node planners share this walk. */
 export function relativeImportSpecifier(fromFile: string, toModule: string): string {
   const from = normalize(fromFile).split('/').filter(Boolean).slice(0, -1);
   const to = normalize(toModule)

package/src/source/reparent-guard.ts

@@ -1,36 +1,7 @@
-/**
- * R3F hierarchy reparent hardening — the PURE plan for "move this JSX element into
- * that one", covering R1 (scope safety), R2 (world-transform preservation) and R3
- * (destination legality) before a single byte is written.
- *
- * Why here: `plan-source-edit.ts` is the ONE place both tiers (dev server and hosted
- * browser) route a source edit through, and its `reparent` case used to be a bare
- * `reparentElement` — a textual line-block move that is sound only between two parents
- * in the same lexical scope with identical accumulated transforms. The moment the
- * hierarchy invites arbitrary drags it is unsound three ways, all of them SILENT:
- *
- *   1. Lexical capture — an element authored inside a component function may reference
- *      that function's own bindings (`color={tint}`, a `ref`, a mapped variable).
- *      Textually moving it elsewhere produces code that does not compile, or compiles
- *      against a DIFFERENT binding with the same name.
- *   2. Transform re-basing — a verbatim move preserves the authored `position` tuple,
- *      not the world position. Between identity parents those are the same thing;
- *      between transformed parents the object teleports on the next mount.
- *   3. Boundary blindness — a self-closing destination (which is what nearly every R3F
- *      component callsite is) made `reparentElement` insert a PRECEDING SIBLING instead
- *      of a child, and a destination rendered N times would author the element once and
- *      render it N times.
- *
- * The response to all three is the same and is the anti-shim rule: REFUSE, naming the
- * thing that made the move unsafe. This module never rewrites an expression, never
- * renames a binding, and never writes a computed value over an authored one — the
- * literal-vs-dynamic guard is as sacred here as at the gizmo.
- *
- * R4 (one transaction) falls out of living here: every rule is decided before the first
- * edit, a refusal returns the input string identity-equal, and an accepted move returns
- * ONE new whole-file string (tuple rewrites + slot opening + the move), which the
- * caller's existing whole-file snapshot inverse turns into a single undo step.
- */
+/** Plan a JSX reparent after checking lexical capture, world-transform
+ * preservation, and destination legality. Unsupported moves return the input
+ * unchanged with a named refusal; accepted moves return one complete next-file
+ * source string for one history transaction. */
 
 import ts from 'typescript';
 import { parseAuthoringTsx } from './ts-ast';
@@ -53,12 +24,8 @@ const EPS = 1e-6;
 
 export interface ReparentOptions {
   readonly rebase?: ReparentRebase | undefined;
-  /**
-   * How many live objects the DESTINATION's oid resolves to. More than one means the
-   * destination is authored once and rendered N times (a `.map`ped callsite, or a
-   * component definition with N instances), so the moved element would be authored
-   * once and rendered N times too — R3 refuses that with the count.
-   */
+  /** Number of live objects sharing the destination OID. Multiple instances
+   * would repeat the moved child, so the planner refuses that destination. */
   readonly destinationInstances?: number | undefined;
   /**
    * The same count for the element being MOVED. More than one is the mirrored case and
@@ -72,7 +39,7 @@ export interface ReparentPlan extends StructEditResult {
   /** The named reason the move was refused. Present iff `changed` is false and the
    *  input was left byte-identical because a rule said no. */
   readonly error?: string;
-  /** Applied, but with something the author should know (R3's mirrored case). */
+  /** Applied with a warning for the author. */
   readonly warning?: string;
 }
 
@@ -115,9 +82,7 @@ function contains(outer: ts.Node, sf: ts.SourceFile, offset: number): boolean {
   return outer.getStart(sf) <= offset && offset < outer.getEnd();
 }
 
-// ------------------------------------------------------------- R1: scope safety
-
-/** Every name a declaration binds, flattened through destructuring patterns. */
+// --- Scope safety ---
 function boundNames(name: ts.BindingName, into: Set<string>): void {
   if (ts.isIdentifier(name)) {
     into.add(name.text);
@@ -227,19 +192,9 @@ function lineOf(node: ts.Node, sf: ts.SourceFile): number {
   return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
 }
 
-/**
- * The identifiers the element's JSX subtree REFERENCES from outside itself — the R1
- * input. Same machinery as the contract analyzer (a plain `ts` walk over the TSX AST).
- *
- * It counts an identifier it is unsure about, so an unrecognized shape refuses rather
- * than moves. The one deliberate subtraction is names the subtree binds FOR ITSELF —
- * without it, a `.map((angle) => …)` inside the moved element would read as a capture
- * of the outer scope and nothing containing a mapped list could ever move. Stated
- * plainly, because it is not free: a name bound inside the subtree in one place and
- * captured from outside it in another is subtracted too, and that capture is missed.
- * A tighter answer needs a real binder, not a name set; this is the honest limit of
- * the cheap one.
- */
+/** Find names referenced outside the subtree. Names bound anywhere inside
+ * it are subtracted; the name-set walk does not resolve shadowed captures.
+ * Unrecognized reference shapes count conservatively as captures. */
 export function referencedIdentifiers(node: JsxElementNode): Map<string, ts.Node> {
   const referenced = new Map<string, ts.Node>();
   const localBindings = new Set<string>();
@@ -295,7 +250,7 @@ function leftmostIdentifier(node: ts.PropertyAccessExpression): ts.Node {
   return cursor;
 }
 
-// -------------------------------------------------- R3: destination legality
+// --- Destination legality ---
 
 type ChildrenSlot = 'paired' | 'expandable';
 
@@ -409,7 +364,7 @@ export function planReparent(
     return refuse(`<${destinationTag}> is inside <${elementTag}> — a move there would be a cycle.`);
   }
 
-  // --- R3: destination legality ------------------------------------------------
+  // --- Destination legality ---
   const destinationInstances = options.destinationInstances;
   if (destinationInstances !== undefined && destinationInstances > 1) {
     return refuse(
@@ -433,7 +388,7 @@ export function planReparent(
     }
   }
 
-  // --- R1: scope safety --------------------------------------------------------
+  // Keep the destination within the element's lexical scope.
   for (const [name, reference] of referencedIdentifiers(element)) {
     const scope = bindingScopeOf(name, reference);
     if (!scope || contains(scope, sf, parentStart)) continue;
@@ -443,7 +398,7 @@ export function planReparent(
     );
   }
 
-  // --- R2: world-transform preservation ---------------------------------------
+  // Preserve the world transform across the new parent.
   const rebase = options.rebase;
   const tagEnd = findTagEnd(code, elementStart);
   if (tagEnd < 0) return refuse(`<${elementTag}>'s opening tag could not be read.`);
@@ -476,7 +431,7 @@ export function planReparent(
     });
   }
 
-  // --- R4: everything above decided; only now does anything get written --------
+  // All checks passed; apply tuple rewrites and the element move.
   let next = code;
   for (const { channel, values, scalar } of pending) {
     const uniform =

package/src/source/source-edit-request.ts

@@ -1,22 +1,4 @@
-/**
- * The SOURCE-EDIT REQUEST — the one wire shape a source edit is stated in, and
- * deliberately its own file.
- *
- * It sits between two programs that must NOT share a type graph: the browser
- * editor (`ui-source/source-write-backend.ts`, which posts it) and the NODE
- * dev server (`vite-plugin-ui-oid.ts`'s middleware and `ui-source/plan-source-edit.ts`,
- * which plan and apply it). Until 2026-09-20 both sides imported the type from
- * `source-write-backend.ts` — and that module value-imports `files/project-files.ts`,
- * which reaches `storage/` and from there the editor SHELL STORE, so
- * `tsconfig.server.json` compiled 231 browser modules including 36 React ones to
- * typecheck a Node program (the fourth blind review's "the Node server's type graph
- * now reaching the browser app"; the config's own header recorded the 310 errors
- * that forced its `paths` and `jsx` settings).
- *
- * So: the REQUEST lives here, importing nothing but its two sibling AST types, and
- * `source-write-backend.ts` re-exports it for the browser callers that already name
- * it. Anything added to this file must stay free of browser and Node imports alike —
- * it is read by both.
- */
+/** Shared source-edit wire contracts, used by browser authoring and the
+ * Node serving plugin without importing either implementation graph. */
 
 export type { PreparedSourceEdit, SourceEditRequest, StructReparentContext } from '@volter/sdk/source-authoring';

package/src/source/ts-ast.ts

@@ -1,72 +1,10 @@
-/**
- * THE MECHANICAL TypeScript-AST HELPERS every `ui-source/` reader repeats.
- *
- * Not an abstraction over the TypeScript compiler API — each function here
- * hands back the compiler's OWN node and gets out of the way, and every caller
- * keeps programming against `ts.*`. What they remove is the retyping: the
- * eleven modules in this directory that read a TSX module each spelled the same
- * four or five little walks out again, and the copies had begun to disagree
- * about things that matter.
- *
- * What "matters" means, concretely — this is the drift these functions existed
- * in nine, three, three, two and two copies of, and what each copy got wrong:
- *
- *   - {@link parseAuthoringTsx}: `ts.createSourceFile(file, code,
- *     ScriptTarget.Latest, true, ScriptKind.TSX)` appeared at NINE sites, two of
- *     them already wrapped in a local `parseTsx`/`sourceFile` whose only
- *     difference was argument order. Both of the last two arguments are silent
- *     if wrong: `setParentNodes: false` leaves `node.parent` undefined, which
- *     breaks every upward walk here (including {@link enclosingScope}) at
- *     runtime rather than at compile time, and a missing `ScriptKind.TSX`
- *     parses JSX as type assertions.
- *   - {@link hasModifier}: two copies, ALREADY drifted —
- *     `plan-fork-component.ts`'s guarded with `ts.canHaveModifiers` and
- *     `r3f-project-contracts.ts`'s cast the node to `ts.HasModifiers` and hoped.
- *     The guarded form is the one kept.
- *   - {@link enclosingScope}: three copies of one loop, returning
- *     `FunctionLikeDeclaration` in two and `SignatureDeclaration` in the third
- *     for the same four node kinds.
- *   - {@link numericLiteral}: three copies (`numeric`, `numericLiteral`) of the
- *     unary-sign rule — the part a fourth author would plausibly write without,
- *     silently losing every negative literal.
- *   - {@link jsxAttribute} / {@link refIdentifier}: two and three copies of
- *     "find this attribute", one of the `refIdentifier`s returning `undefined`
- *     where the others return `null`.
- *
- * Deliberately NOT here: anything whose two versions differ for a caller's own
- * reason. `plan-fork-component.ts`'s `jsxAtOffset` and `reparent-guard.ts`'s
- * `jsxElementAt` look like twins and are not — one wants the OPENING element to
- * read its tag, the other wants the whole `ts.JsxElement` to move it, and the
- * second prunes the walk by span while the first does not.
- */
+/** Shared TypeScript AST helpers. Callers retain compiler nodes, parent
+ * pointers, and JSX syntax for their own source analyses. */
 
 import * as ts from 'typescript';
 
-/**
- * Parse one authored TSX/TS module the way every reader in this directory
- * needs it: newest syntax, parent pointers set, JSX enabled.
- *
- * `file` is the module's path — it is what the compiler reports in positions
- * and what `node.getText(sf)` reads against, so pass the real one where there
- * is one.
- */
-/**
- * ONE parse per (file, bytes) — the same source is parsed several times over
- * for one bundle otherwise.
- *
- * `ProjectContractResolver` calls this three times for a single file
- * (`importedForSource`, `typeAliasesForSource`, `propSpecsForSource`), the
- * stamping transform parses it again, and every one of those runs on EVERY
- * structural edit.
- * Measured on `examples/third-person`, the contract walk alone costs 380ms of
- * the ~1.1s an edit spends on CPU.
- *
- * Keyed on the BYTES, so it is sound in a way an analysis cache is not: a
- * parse is a pure function of its input, while what a file MEANS also depends
- * on the files it imports. Edited bytes miss the cache and re-parse; the entry
- * for the old bytes is dropped, so the map holds one node tree per live file
- * rather than one per revision.
- */
+/** Parse TSX with current syntax and parent pointers. Cache one parse per
+ * file and exact source text; changed bytes replace the previous tree. */
 const parsedByFile = new Map<
   string,
   { readonly code: string; readonly sourceFile: ts.SourceFile }
@@ -86,14 +24,6 @@ export function parseAuthoringTsx(file: string, code: string): ts.SourceFile {
   return sourceFile;
 }
 
-/** Drop every cached parse — for a project switch, where the next project's
- *  files may reuse these paths with different bytes. Bytes are compared on
- *  every hit anyway, so this is hygiene against unbounded growth, not
- *  correctness. */
-export function clearAuthoringParseCache(): void {
-  parsedByFile.clear();
-}
-
 /** Whether `node` carries a given modifier (`export`, `default`, …). False for
  *  a node kind that cannot carry modifiers at all, rather than throwing. */
 export function hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
@@ -124,29 +54,9 @@ export function enclosingScope(node: ts.Node): ts.FunctionLikeDeclaration | null
   return null;
 }
 
-/**
- * The number an expression literally IS, or `undefined` when it is anything
- * computed. A leading `-`/`+` counts: `position={[-1, 0, 2]}` is authored
- * constantly and its first entry is a `PrefixUnaryExpression`, not a numeric
- * literal.
- */
-export function numericLiteral(expression: ts.Expression): number | undefined {
-  if (ts.isNumericLiteral(expression)) return Number(expression.text);
-  if (
-    ts.isPrefixUnaryExpression(expression) &&
-    (expression.operator === ts.SyntaxKind.MinusToken ||
-      expression.operator === ts.SyntaxKind.PlusToken) &&
-    ts.isNumericLiteral(expression.operand)
-  ) {
-    const value = Number(expression.operand.text);
-    return expression.operator === ts.SyntaxKind.MinusToken ? -value : value;
-  }
-  return undefined;
-}
-
 /** The named attribute on a JSX opening element, or `undefined`. Spread
  *  attributes are not attributes and are skipped. */
-export function jsxAttribute(
+function jsxAttribute(
   element: ts.JsxOpeningLikeElement,
   name: string,
 ): ts.JsxAttribute | undefined {

package/src/source/utility-class-support.ts

@@ -1,35 +1,7 @@
-/**
- * "Does THIS project interpret utility classes?" — the evidence gate in front of
- * `writeStyleAuto`'s className route.
- *
- * Why it exists: the router used to pick the Tailwind arbitrary-value class
- * (`bg-[#059669]`) whenever an element merely HAD a literal `className`, with no
- * evidence anything would ever compile that class. On a plain-CSS project the
- * write lands in source and paints NOTHING — measured on the vendored pmndrs
- * racing-game (plain Vite + `src/styles.css`, no tailwind in its tree or ours):
- * the editor's visible result was only the adapter's optimistic inline patch, a
- * cold remount rendered `rgba(0, 0, 0, 0)`, and the game's own build has no
- * transformer for it either. Inert bytes in someone's source that tell a lie
- * about their game.
- *
- * The fix is the same observation-over-inference rule the OID dialect decision
- * follows: route on what was OBSERVED about the project, not on what the
- * element's shape suggests. A tier gathers evidence with whatever I/O it has
- * (`node:fs` on the dev server, `StorageBackend` in the hosted browser) and
- * hands the bytes here; the decision itself is pure and lives ONLY here, so the
- * two tiers cannot drift into different answers.
- *
- * **The probe is deliberately strict, and the asymmetry is why.** A false
- * NEGATIVE costs an inline `style={{…}}` write — a less idiomatic expression of
- * the same edit that paints correctly in every project, in and out of the
- * editor. A false POSITIVE costs a write that is a lie. So "a dependency is
- * listed" is not enough on its own: something must also show the pipeline is
- * actually wired (a config file, a postcss/vite/astro plugin mention, or a css
- * entry that imports the framework). A CDN/runtime interpreter in HTML stands
- * alone because it needs no build step at all.
- */
-
-/** The routing answer, plus what was actually observed to produce it. */
+/** Determine whether project evidence proves that utility classes are compiled
+ * or interpreted. A declared dependency needs matching pipeline configuration;
+ * a CDN interpreter needs no build step. Unproven support routes style writes
+ * to inline CSS. The probe is pure; callers supply the files they can read. */
 export interface UtilityClassSupport {
   /** True only when the project was OBSERVED to interpret utility classes. */
   readonly supported: boolean;