@scenoco-three/tools 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SceNoCo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @scenoco-three/tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What works on SceNoCo scene files rather than in the game.
+
+```bash
+npm install -D @scenoco-three/tools
+scenoco check src        # every .tsx file is a scene, and a scene only declares
+```
+
+A scene may import, define constants of plain data, and export functions that make refs and return
+TSX. Inside the TSX a value is a literal, a list or object of them, arithmetic on them
+(`-Math.PI / 2`), or a name. Anything that runs — a loop, a branch, a handler, a call, a hook — is a
+behaviour's job, in a `.ts` file, and each refusal says where and what to write instead. Types are
+`tsc`'s job; a project's `check` script runs both: `tsc --noEmit && scenoco check src`.
+
+The rule exists so a tool can edit a scene. `readScene`, `setAttribute`, `insertChild`,
+`removeElement` and friends read a scene file without running it and write by splicing exactly the
+text that changed — everything else, comments and layout included, stays byte for byte. Elements are
+found by the line and column the runtime's `sourceOf` reports, so a picked object leads to its tag.

package/bin/scenoco.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The `scenoco` command. A file that exists before the build, because npm links a workspace's
+// bin only if its target is there at install time — and a fresh checkout installs before it builds.
+import '../dist/cli.js';

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * `scenoco check [dir...]` — every `.tsx` file under the given folders (the current one by
+ * default) is a scene, and a scene only declares. Types are `tsc`'s job; this is the other half.
+ */
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import process from 'node:process';
+import { checkScene, tsxFiles } from './scenes.js';
+const [command, ...dirs] = process.argv.slice(2);
+if (command !== 'check') {
+    console.error('usage: scenoco check [dir...]   — every .tsx file is a scene, and a scene only declares');
+    process.exit(command === undefined || command === '-h' || command === '--help' ? 0 : 1);
+}
+const problems = (dirs.length ? dirs : ['.'])
+    .flatMap((dir) => [...tsxFiles(dir)])
+    .flatMap((file) => checkScene(relative(process.cwd(), file), readFileSync(file, 'utf8')));
+for (const problem of problems)
+    console.error(problem);
+if (problems.length) {
+    console.error(`\n${problems.length} problem(s). A .tsx file is a scene: it declares, and behaviours (.ts) do the rest.`);
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@scenoco-three/tools` — what works on scene files rather than in the game: the rule that a
+ * `.tsx` file only declares, and the editor's way to read and edit one without losing a byte of
+ * what was not touched.
+ */
+export { checkScene, tsxFiles } from './scenes.js';
+export * from './scene-edit.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@scenoco-three/tools` — what works on scene files rather than in the game: the rule that a
+ * `.tsx` file only declares, and the editor's way to read and edit one without losing a byte of
+ * what was not touched.
+ */
+export { checkScene, tsxFiles } from './scenes.js';
+export * from './scene-edit.js';

package/dist/scene-edit.d.ts

@@ -0,0 +1,54 @@
+/** What an attribute holds, as far as reading it without running anything can tell. */
+export type Value = {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'reference';
+    text: string;
+};
+export interface Attribute {
+    name: string;
+    /** The whole attribute, `name={…}`, in the file. */
+    start: number;
+    end: number;
+    /** Its value's text as written, or null for a bare flag (`castShadow`). */
+    text: string | null;
+    value: Value;
+}
+export interface Element {
+    tag: string;
+    /** 1-based, at the `<` — what `jsxDEV`'s source says. */
+    line: number;
+    column: number;
+    start: number;
+    end: number;
+    /** Where a new attribute goes: just before `>` or `/>` of the opening tag. */
+    attributesEnd: number;
+    selfClosing: boolean;
+    /** Start of `</Tag>`, where a new child goes; the element's end when self-closing. */
+    closingStart: number;
+    attributes: Attribute[];
+    children: Element[];
+}
+export interface SceneDocument {
+    code: string;
+    /** Elements not inside another element: what each scene or prefab function returns. */
+    roots: Element[];
+}
+export declare function readScene(file: string, code: string): SceneDocument;
+/** Every element of the document, depth first. */
+export declare function elements(doc: SceneDocument): Element[];
+/** The element written at this line and column — `sourceOf(object)` of what it made. */
+export declare function elementAt(doc: SceneDocument, line: number, column: number): Element | undefined;
+/** Set an attribute to a value, replacing what was written or adding it at the end of the tag. */
+export declare function setAttribute(code: string, element: Element, name: string, value: unknown): string;
+/** Set an attribute to text as written — `{-Math.PI / 2}`, `"red"` — or to a bare flag (null). */
+export declare function setAttributeText(code: string, element: Element, name: string, text: string | null): string;
+/** Remove an attribute, with the space before it. */
+export declare function removeAttribute(code: string, element: Element, name: string): string;
+/** Remove an element; the whole line goes with it when it stood alone there. */
+export declare function removeElement(code: string, element: Element): string;
+/** Add a child at the end of an element, indented like its siblings. */
+export declare function insertChild(code: string, parent: Element, tsx: string): string;
+/** How a value is written as an attribute: `"…"` for a string, `{…}` for everything else. */
+export declare function attributeText(value: unknown): string;

package/dist/scene-edit.js

@@ -0,0 +1,281 @@
+/**
+ * Edit a TSX scene the way a person in an editor does — move a node, recolour a material, add or
+ * remove an element — by splicing the text of exactly what changed. Everything else in the file,
+ * comments and layout included, stays byte for byte.
+ *
+ * Reading is generous: a value is shown when it can be worked out without running anything —
+ * literals, arithmetic, `Math.PI`, a constant of this file — and as a named reference otherwise
+ * (`paint.grass`, a ref, a prefab). Writing is plain: the new value replaces the old text as a
+ * literal, so a dragged `rotation={[-Math.PI / 2, 0, 0]}` comes back as numbers. That loss is the
+ * price of a person's edit, and only of the attribute they touched.
+ *
+ * Elements are found by where they were written — the same line and column `jsxDEV` gives the
+ * runtime (see `sourceOf`), so a picked object leads straight to its tag.
+ */
+import { parseSync } from 'rolldown/utils';
+export function readScene(file, code) {
+    const { program, errors } = parseSync(file, code, { lang: 'tsx' });
+    if (errors.length)
+        throw new Error(`${file}: ${errors[0].message}`);
+    const lineStarts = [0];
+    for (let i = 0; i < code.length; i++)
+        if (code[i] === '\n')
+            lineStarts.push(i + 1);
+    const position = (offset) => {
+        let lo = 0;
+        let hi = lineStarts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (lineStarts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return { line: lo + 1, column: offset - lineStarts[lo] + 1 };
+    };
+    const constants = new Map();
+    const evaluate = (node) => {
+        const seen = staticValue(node, constants);
+        return seen === UNKNOWN ? { kind: 'reference', text: code.slice(node.start, node.end) } : { kind: 'value', value: seen };
+    };
+    // Constants of this file whose values can be worked out, so `position={[LANE, 0, 0]}` reads as numbers.
+    for (const statement of program.body) {
+        const declaration = (statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement);
+        if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'const')
+            continue;
+        for (const d of declaration.declarations) {
+            const id = d.id;
+            const init = d.init;
+            if (id.type === 'Identifier' && init) {
+                const value = staticValue(init, constants);
+                if (value !== UNKNOWN)
+                    constants.set(id.name, value);
+            }
+        }
+    }
+    const element = (node) => {
+        const opening = node.openingElement;
+        const selfClosing = opening.selfClosing === true;
+        const attributes = [];
+        for (const attr of opening.attributes) {
+            if (attr.type !== 'JSXAttribute')
+                continue;
+            const name = code.slice(attr.name.start, attr.name.end);
+            const raw = attr.value;
+            if (!raw) {
+                attributes.push({ name, start: attr.start, end: attr.end, text: null, value: { kind: 'value', value: true } });
+                continue;
+            }
+            const inner = raw.type === 'JSXExpressionContainer' ? raw.expression : raw;
+            attributes.push({ name, start: attr.start, end: attr.end, text: code.slice(raw.start, raw.end), value: evaluate(inner) });
+        }
+        const children = [];
+        for (const child of node.children) {
+            if (child.type === 'JSXElement')
+                children.push(element(child));
+        }
+        const closing = node.closingElement;
+        const at = position(node.start);
+        return {
+            tag: code.slice(opening.name.start, opening.name.end),
+            line: at.line,
+            column: at.column,
+            start: node.start,
+            end: node.end,
+            attributesEnd: code.lastIndexOf(selfClosing ? '/>' : '>', opening.end - 1),
+            selfClosing,
+            closingStart: closing ? closing.start : node.end,
+            attributes,
+            children,
+        };
+    };
+    const roots = [];
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node))
+            return node.forEach(visit);
+        const n = node;
+        if (n.type === 'JSXElement')
+            return void roots.push(element(n));
+        for (const [key, value] of Object.entries(n))
+            if (key !== 'start' && key !== 'end')
+                visit(value);
+    };
+    visit(program);
+    return { code, roots };
+}
+/** Every element of the document, depth first. */
+export function elements(doc) {
+    const out = [];
+    const walk = (e) => {
+        out.push(e);
+        e.children.forEach(walk);
+    };
+    doc.roots.forEach(walk);
+    return out;
+}
+/** The element written at this line and column — `sourceOf(object)` of what it made. */
+export function elementAt(doc, line, column) {
+    return elements(doc).find((e) => e.line === line && e.column === column);
+}
+/** Set an attribute to a value, replacing what was written or adding it at the end of the tag. */
+export function setAttribute(code, element, name, value) {
+    const existing = element.attributes.find((a) => a.name === name);
+    return setAttributeText(code, element, name, value === true && existing?.text === null ? null : attributeText(value));
+}
+/** Set an attribute to text as written — `{-Math.PI / 2}`, `"red"` — or to a bare flag (null). */
+export function setAttributeText(code, element, name, text) {
+    const existing = element.attributes.find((a) => a.name === name);
+    const written = text === null ? name : `${name}=${text}`;
+    if (existing)
+        return splice(code, existing.start, existing.end, written);
+    const last = element.attributes.at(-1);
+    if (last && code.slice(last.end, element.attributesEnd).includes('\n')) {
+        // One attribute per line: a new line after the last one, indented like it.
+        const lineStart = code.lastIndexOf('\n', last.start - 1) + 1;
+        const indent = /^\s*/.exec(code.slice(lineStart, last.start))[0];
+        return splice(code, last.end, last.end, `\n${indent}${written}`);
+    }
+    // On the tag's line: `<Group>` → `<Group a={1}>`, `<Mesh b />` → `<Mesh b a={1} />`.
+    const spaced = /\s$/.test(code.slice(0, element.attributesEnd));
+    return splice(code, element.attributesEnd, element.attributesEnd, spaced ? `${written} ` : ` ${written}`);
+}
+/** Remove an attribute, with the space before it. */
+export function removeAttribute(code, element, name) {
+    const existing = element.attributes.find((a) => a.name === name);
+    if (!existing)
+        return code;
+    let start = existing.start;
+    while (start > 0 && /[ \t]/.test(code[start - 1]))
+        start--;
+    if (code[start - 1] === '\n') {
+        start = existing.start;
+        while (start > 0 && code[start - 1] !== '\n')
+            start--;
+        return splice(code, start - 1, existing.end, '');
+    }
+    return splice(code, start, existing.end, '');
+}
+/** Remove an element; the whole line goes with it when it stood alone there. */
+export function removeElement(code, element) {
+    let start = element.start;
+    let end = element.end;
+    const lineStart = code.lastIndexOf('\n', start - 1) + 1;
+    const lineEnd = code.indexOf('\n', end);
+    if (/^\s*$/.test(code.slice(lineStart, start)) && /^\s*$/.test(code.slice(end, lineEnd === -1 ? code.length : lineEnd))) {
+        start = lineStart;
+        end = lineEnd === -1 ? code.length : lineEnd + 1;
+    }
+    return splice(code, start, end, '');
+}
+/** Add a child at the end of an element, indented like its siblings. */
+export function insertChild(code, parent, tsx) {
+    const lineStart = code.lastIndexOf('\n', parent.start - 1) + 1;
+    const indent = /^\s*/.exec(code.slice(lineStart, parent.start))[0];
+    const inner = `${indent}  `;
+    if (parent.selfClosing) {
+        const open = code.slice(parent.start, parent.attributesEnd).replace(/\s+$/, '');
+        return splice(code, parent.start, parent.end, `${open}>\n${inner}${tsx}\n${indent}</${parent.tag}>`);
+    }
+    const closingLineStart = code.lastIndexOf('\n', parent.closingStart - 1) + 1;
+    const onOwnLine = /^\s*$/.test(code.slice(closingLineStart, parent.closingStart));
+    return onOwnLine
+        ? splice(code, closingLineStart, closingLineStart, `${inner}${tsx}\n`)
+        : splice(code, parent.closingStart, parent.closingStart, `\n${inner}${tsx}\n${indent}`);
+}
+/** How a value is written as an attribute: `"…"` for a string, `{…}` for everything else. */
+export function attributeText(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : `{${expressionText(value)}}`;
+}
+function expressionText(value) {
+    if (typeof value === 'number')
+        return numberText(value);
+    if (typeof value === 'string' || typeof value === 'boolean' || value === null)
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(expressionText).join(', ')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).map(([k, v]) => `${/^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k)}: ${expressionText(v)}`);
+        return `{ ${entries.join(', ')} }`;
+    }
+    throw new Error(`cannot write ${String(value)} into a scene`);
+}
+/** Four decimals at most — an editor's drag does not need more — and no `-0`. */
+function numberText(n) {
+    const rounded = Math.round(n * 1e4) / 1e4;
+    return String(Object.is(rounded, -0) ? 0 : rounded);
+}
+function splice(code, start, end, text) {
+    return code.slice(0, start) + text + code.slice(end);
+}
+const UNKNOWN = Symbol('unknown');
+/** A value worked out without running anything, or UNKNOWN. */
+function staticValue(node, constants) {
+    switch (node.type) {
+        case 'Literal':
+            return node.value;
+        case 'TemplateLiteral':
+            return node.expressions.length ? UNKNOWN : node.quasis[0].value.cooked;
+        case 'ParenthesizedExpression':
+        case 'TSAsExpression':
+        case 'TSNonNullExpression':
+            return staticValue(node.expression, constants);
+        case 'Identifier':
+            return constants.has(node.name) ? constants.get(node.name) : UNKNOWN;
+        case 'UnaryExpression': {
+            const v = staticValue(node.argument, constants);
+            if (typeof v !== 'number')
+                return UNKNOWN;
+            return node.operator === '-' ? -v : node.operator === '+' ? v : UNKNOWN;
+        }
+        case 'BinaryExpression': {
+            const a = staticValue(node.left, constants);
+            const b = staticValue(node.right, constants);
+            if (typeof a !== 'number' || typeof b !== 'number')
+                return UNKNOWN;
+            switch (node.operator) {
+                case '+': return a + b;
+                case '-': return a - b;
+                case '*': return a * b;
+                case '/': return a / b;
+                case '%': return a % b;
+                default: return UNKNOWN;
+            }
+        }
+        case 'MemberExpression': {
+            const object = node.object;
+            const property = node.property;
+            if (!node.computed && object.type === 'Identifier' && object.name === 'Math' && property.type === 'Identifier') {
+                const v = Math[property.name];
+                return typeof v === 'number' ? v : UNKNOWN;
+            }
+            return UNKNOWN;
+        }
+        case 'ArrayExpression': {
+            const out = [];
+            for (const item of node.elements) {
+                const v = item ? staticValue(item, constants) : UNKNOWN;
+                if (v === UNKNOWN)
+                    return UNKNOWN;
+                out.push(v);
+            }
+            return out;
+        }
+        case 'ObjectExpression': {
+            const out = {};
+            for (const prop of node.properties) {
+                if (prop.type !== 'Property' || prop.computed)
+                    return UNKNOWN;
+                const key = prop.key;
+                const v = staticValue(prop.value, constants);
+                if (v === UNKNOWN)
+                    return UNKNOWN;
+                out[(key.name ?? key.value)] = v;
+            }
+            return out;
+        }
+        default:
+            return UNKNOWN;
+    }
+}

package/dist/scenes.d.ts

@@ -0,0 +1,3 @@
+export declare function checkScene(file: string, code: string): string[];
+/** Every `.tsx` file under `dir`, past `node_modules`, `dist` and dotted folders. */
+export declare function tsxFiles(dir: string): Generator<string>;

package/dist/scenes.js

@@ -0,0 +1,188 @@
+/**
+ * Every `.tsx` file is a scene, and a scene only declares.
+ *
+ * A scene file may import, define constants of plain data, and export functions that make refs and
+ * return TSX. Inside the TSX a value is a literal, a list or object of them, arithmetic on them
+ * (`-Math.PI / 2`), or a name. Anything that runs — a loop, a branch, a handler, a call, a hook — is
+ * a component's job, in a `.ts` file. Each refusal says where and what to write instead.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSync } from 'rolldown/utils';
+const LOOP = 'a scene has no loops — to place many, spawn them from a component with instantiate(Prefab)';
+const BRANCH = 'a scene has no branches — show or hide from a component (node.visible, or destroy)';
+const HANDLER = 'a scene has no handlers — what happens goes in a component: a class in a .ts file, with update()';
+const HOOK = 'there is no React here — TSX builds three.js objects once; what runs each frame is a component\'s update()';
+const CALL = 'a scene calls nothing — a value is a literal, a list or object of them, arithmetic like -Math.PI / 2, or a name';
+export function checkScene(file, code) {
+    const problems = [];
+    const at = (node, message) => {
+        const before = code.slice(0, node.start).split('\n');
+        problems.push(`${file}:${before.length}:${before.at(-1).length + 1}  ${message}`);
+    };
+    const { program, errors } = parseSync(file, code, { lang: 'tsx' });
+    if (errors.length)
+        return [`${file}  ${errors[0].message}`];
+    /** A value that is data: literals, lists and objects of them, arithmetic on them, names and their members. */
+    const value = (node) => {
+        if (!node)
+            return;
+        switch (node.type) {
+            case 'Literal':
+            case 'Identifier':
+            case 'JSXEmptyExpression':
+                return;
+            case 'TemplateLiteral':
+                if (node.expressions.length)
+                    at(node, CALL);
+                return;
+            case 'ParenthesizedExpression':
+            case 'TSAsExpression':
+            case 'TSNonNullExpression':
+                return value(node.expression);
+            case 'UnaryExpression':
+                return ['-', '+'].includes(node.operator) ? value(node.argument) : at(node, CALL);
+            case 'BinaryExpression':
+                if (!['+', '-', '*', '/', '%'].includes(node.operator))
+                    return at(node, BRANCH);
+                value(node.left);
+                return value(node.right);
+            case 'MemberExpression':
+                if (node.computed)
+                    return at(node, CALL);
+                return value(node.object);
+            case 'ArrayExpression':
+                for (const item of node.elements)
+                    item?.type === 'SpreadElement' ? at(item, CALL) : value(item);
+                return;
+            case 'ObjectExpression':
+                for (const prop of node.properties) {
+                    if (prop.type !== 'Property' || prop.computed)
+                        at(prop, CALL);
+                    else
+                        value(prop.value);
+                }
+                return;
+            case 'JSXElement':
+            case 'JSXFragment':
+                return tsx(node);
+            case 'ConditionalExpression':
+            case 'LogicalExpression':
+                return at(node, BRANCH);
+            case 'ArrowFunctionExpression':
+            case 'FunctionExpression':
+                return at(node, HANDLER);
+            case 'CallExpression': {
+                const callee = node.callee;
+                const name = callee.type === 'Identifier' ? callee.name : callee.type === 'MemberExpression' ? callee.property.name : '';
+                if (/^use[A-Z]/.test(name))
+                    return at(node, HOOK);
+                if (['map', 'forEach', 'from', 'flatMap', 'filter'].includes(name))
+                    return at(node, LOOP);
+                return at(node, CALL);
+            }
+            default:
+                return at(node, CALL);
+        }
+    };
+    /** An element: its attributes are values, its children elements, names or comments. */
+    const tsx = (node) => {
+        if (node.type === 'JSXElement') {
+            for (const attr of node.openingElement.attributes) {
+                if (attr.type === 'JSXSpreadAttribute')
+                    at(attr, 'a scene spells out its attributes — no spread');
+                else if (attr.value?.type === 'JSXExpressionContainer')
+                    value(attr.value.expression);
+            }
+        }
+        for (const child of node.children) {
+            if (child.type === 'JSXText') {
+                const text = child.value;
+                const lead = text.length - text.trimStart().length;
+                if (text.trim())
+                    at({ ...child, start: child.start + lead }, 'text in a scene is a value — an attribute, or a component\'s field');
+            }
+            else if (child.type === 'JSXExpressionContainer') {
+                const inner = child.expression;
+                if (inner.type !== 'JSXEmptyExpression' && inner.type !== 'Identifier')
+                    value(inner);
+            }
+            else
+                tsx(child);
+        }
+    };
+    /** A factory: `() => <Tsx/>`, or a body of `const x = ref<T>()` and plain constants, then one `return`. */
+    const factory = (fn) => {
+        const body = fn.body;
+        if (body.type !== 'BlockStatement')
+            return value(body);
+        const statements = body.body;
+        statements.forEach((statement, i) => {
+            if (statement.type === 'ReturnStatement' && i === statements.length - 1)
+                return value(statement.argument);
+            if (statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+                for (const d of statement.declarations) {
+                    const init = d.init;
+                    if (init?.type === 'CallExpression' && init.callee.name === 'ref')
+                        continue;
+                    value(init);
+                }
+                return;
+            }
+            at(statement, statement.type === 'IfStatement' ? BRANCH : /For|While/.test(statement.type) ? LOOP : HANDLER);
+        });
+    };
+    const declaration = (node) => {
+        if (node.type === 'FunctionDeclaration')
+            return factory(node);
+        if (node.type === 'VariableDeclaration') {
+            if (node.kind !== 'const')
+                return at(node, 'a scene declares constants only — const');
+            for (const d of node.declarations) {
+                const init = d.init;
+                if (init && /Function/.test(init.type))
+                    factory(init);
+                else if (init?.type === 'CallExpression' && init.callee.name === 'ref') {
+                    at(init, 'make a ref inside the function that uses it — one at module level is shared by every copy');
+                }
+                else
+                    value(init);
+            }
+            return;
+        }
+        if (node.type === 'ClassDeclaration')
+            return at(node, 'a component is a class in a .ts file — a .tsx file is a scene');
+        if (/^TS(Interface|TypeAlias)Declaration$/.test(node.type))
+            return;
+        at(node, HANDLER);
+    };
+    for (const statement of program.body) {
+        if (statement.type === 'ImportDeclaration')
+            continue;
+        if (statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration') {
+            const inner = statement.declaration;
+            if (!inner)
+                continue; // export { … } from
+            if (statement.type === 'ExportDefaultDeclaration' && !/Declaration$/.test(inner.type)) {
+                /Function/.test(inner.type) ? factory(inner) : value(inner);
+            }
+            else
+                declaration(inner);
+            continue;
+        }
+        declaration(statement);
+    }
+    return problems;
+}
+/** Every `.tsx` file under `dir`, past `node_modules`, `dist` and dotted folders. */
+export function* tsxFiles(dir) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === 'node_modules' || entry === 'dist' || entry.startsWith('.'))
+            continue;
+        const path = join(dir, entry);
+        if (statSync(path).isDirectory())
+            yield* tsxFiles(path);
+        else if (path.endsWith('.tsx'))
+            yield path;
+    }
+}

package/dist/vite.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from 'node:http';
+import { type Plugin } from 'vite';
+import { type Value } from './scene-edit.js';
+/** A scene file as the editor sees it: its elements, flat, in document order. */
+export interface SceneJson {
+    file: string;
+    elements: {
+        tag: string;
+        line: number;
+        column: number;
+        /** Index of the enclosing element, or -1 for a root. */
+        parent: number;
+        attributes: {
+            name: string;
+            text: string | null;
+            value: Value;
+        }[];
+    }[];
+}
+export declare function scenoco(): Plugin;
+/** @internal one editor request, answered as JSON. Exported for the test. */
+export declare function handle(root: string, req: IncomingMessage, written: Set<string>): Promise<SceneJson>;

package/dist/vite.js

@@ -0,0 +1,143 @@
+/**
+ * `scenoco()` — the Vite plugin a SceNoCo project uses: TSX through core's JSX runtime, and, while
+ * serving, what the editor needs to read and write scene files.
+ *
+ * ```ts
+ * // vite.config.ts
+ * export default defineConfig({ plugins: [scenoco()] });
+ * ```
+ *
+ * The editor runs in the game's own page (`?edit`), so it asks this server, never the disk:
+ *
+ * - `GET /__scenoco/scene?file=…` — a scene file read without running it: every element in
+ *   document order, with its attributes' values where they can be worked out.
+ * - `POST /__scenoco/set` — `{ file, index, expect, name, value }`: one attribute of one element,
+ *   written by splicing its text (`scene-edit.ts`); everything else in the file stays byte for byte.
+ *   `text` in place of `value` writes the attribute's text exactly as given — what undo puts back.
+ * - `POST /__scenoco/remove` — `{ file, index, expect, name }`.
+ *
+ * An element is addressed by its index in document order, which an attribute edit never changes.
+ * `expect` is the element as the editor last read it — `{ tag, line, column }` — so a file changed
+ * behind the editor's back (in an IDE, by an agent) is refused, never written at the wrong element.
+ * A file the editor just wrote does not reload the page: the editor has already changed the live
+ * object, and a reload would lose the camera and the selection.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { version } from 'vite';
+import { elements, readScene, removeAttribute, setAttribute, setAttributeText } from './scene-edit.js';
+export function scenoco() {
+    let root = process.cwd();
+    /** Files this server just wrote for the editor: their next change is not a reload. */
+    const written = new Set();
+    return {
+        name: 'scenoco',
+        config: () => ({
+            // Vite 8 transforms with oxc; 6 and 7 with esbuild, and 8 warns about the other's option.
+            ...(Number(version.split('.')[0]) >= 8
+                ? { oxc: { jsx: { runtime: 'automatic', importSource: '@scenoco-three/core' } } }
+                : { esbuild: { jsx: 'automatic', jsxImportSource: '@scenoco-three/core' } }),
+            // One `three` in the graph, or `instanceof` across two copies of it silently returns false.
+            resolve: { dedupe: ['three'] },
+        }),
+        configResolved(config) {
+            root = config.root;
+        },
+        configureServer(server) {
+            server.middlewares.use('/__scenoco/', (req, res) => {
+                handle(root, req, written)
+                    .then((body) => send(res, 200, body))
+                    .catch((error) => send(res, 400, { error: error instanceof Error ? error.message : String(error) }));
+            });
+        },
+        handleHotUpdate({ file }) {
+            if (written.delete(file))
+                return [];
+        },
+    };
+}
+/** @internal one editor request, answered as JSON. Exported for the test. */
+export async function handle(root, req, written) {
+    const url = new URL(req.url ?? '/', 'http://x');
+    if (req.method === 'GET' && url.pathname === '/scene')
+        return sceneJson(sceneFile(root, url.searchParams.get('file')));
+    if (req.method !== 'POST')
+        throw new Error(`no ${req.method} ${url.pathname}`);
+    const body = JSON.parse(await text(req));
+    const file = sceneFile(root, body.file ?? null);
+    const code = readFileSync(file, 'utf8');
+    const all = elements(readScene(file, code));
+    const element = all[body.index ?? -1];
+    const expected = body.expect;
+    if (!expected)
+        throw new Error('which element? `expect: { tag, line, column }`, as the editor last read it');
+    if (!element || element.tag !== expected.tag || element.line !== expected.line || element.column !== expected.column) {
+        const now = element ? `<${element.tag}> at ${element.line}:${element.column}` : 'gone';
+        throw new Error(`${relative(root, file)} changed outside the editor: element ${body.index} is ${now}, not <${expected.tag}> at ${expected.line}:${expected.column}. Reload the page.`);
+    }
+    if (typeof body.name !== 'string' || !/^[A-Za-z_$][\w$-]*$/.test(body.name))
+        throw new Error(`not an attribute name: ${body.name}`);
+    let next;
+    if (url.pathname === '/set' && body.text !== undefined)
+        next = setAttributeText(code, element, body.name, body.text);
+    else if (url.pathname === '/set')
+        next = setAttribute(code, element, body.name, body.value);
+    else if (url.pathname === '/remove')
+        next = removeAttribute(code, element, body.name);
+    else
+        throw new Error(`no POST ${url.pathname}`);
+    // Text from the page is checked before it lands: the file must still parse, element for element.
+    let parsed;
+    try {
+        parsed = elements(readScene(file, next)).length;
+    }
+    catch {
+        parsed = -1;
+    }
+    if (parsed !== all.length)
+        throw new Error(`not an attribute value: ${body.text ?? JSON.stringify(body.value)}`);
+    if (next !== code) {
+        written.add(file);
+        writeFileSync(file, next);
+    }
+    return sceneJson(file);
+}
+/** A `.tsx` file inside the project — the only thing the editor may read or write. */
+function sceneFile(root, file) {
+    if (!file)
+        throw new Error('which file? ?file=…');
+    // What `jsxDEV` reports: an absolute path, or one from the project's root.
+    const path = isAbsolute(file) && file.startsWith(root) ? file : resolve(root, `.${file.startsWith('/') ? '' : '/'}${file}`);
+    const inside = relative(root, path);
+    if (inside.startsWith('..') || isAbsolute(inside) || !path.endsWith('.tsx'))
+        throw new Error(`${file} is not a scene file of this project`);
+    return path;
+}
+function sceneJson(file) {
+    const all = elements(readScene(file, readFileSync(file, 'utf8')));
+    const parents = new Map();
+    all.forEach((element, i) => element.children.forEach((child) => parents.set(child, i)));
+    return {
+        file,
+        elements: all.map((element) => ({
+            tag: element.tag,
+            line: element.line,
+            column: element.column,
+            parent: parents.get(element) ?? -1,
+            attributes: element.attributes.map(({ name, text, value }) => ({ name, text, value })),
+        })),
+    };
+}
+function text(req) {
+    return new Promise((done, fail) => {
+        let body = '';
+        req.on('data', (chunk) => (body += chunk));
+        req.on('end', () => done(body));
+        req.on('error', fail);
+    });
+}
+function send(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(body));
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@scenoco-three/tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "SceNoCo's tools: `scenoco check` (a .tsx scene only declares), the `scenoco()` Vite plugin, and the read/edit layer the editor uses on scene files.",
+  "keywords": [
+    "three",
+    "threejs",
+    "scenoco",
+    "game-engine",
+    "game-framework",
+    "gamedev",
+    "web-game",
+    "webgl",
+    "typescript",
+    "unity",
+    "tsx",
+    "vite-plugin",
+    "cli",
+    "lint"
+  ],
+  "homepage": "https://github.com/RomaRogov/scenoco-three/tree/main/packages/tools#readme",
+  "bugs": "https://github.com/RomaRogov/scenoco-three/issues",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RomaRogov/scenoco-three.git",
+    "directory": "packages/tools"
+  },
+  "bin": {
+    "scenoco": "./bin/scenoco.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "rolldown": "^1.0.3"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  }
+}