workstar-compiler 0.1.0 → 0.2.0-beta.0

package/README.md

@@ -10,10 +10,21 @@ The `workstar-compile` command compiles one component or a directory:
 workstar-compile --all src .workstar/generated --css .workstar/styles.css
 ```
 
-For Vite, import `workstar` from `workstar-compiler/vite` and add `workstar()` to `plugins`. Vite compiles imported components in memory; the CLI is for explicit output and type checking.
+For Vite, import `workstar` from `workstar-compiler/vite` and add `workstar()` to `plugins`. Vite compiles explicit `?workstar` component imports in memory. Use `workstar({ foreign: 'automatic' })` to compile ordinary TSX/Vue imports under `src`, including a supported `createRoot(...).render(...)` entry. Use `workstar({ foreign: 'runtime' })` for unchanged React TSX applications that need Workstar-backed state and routing. The runtime mode is experimental and does not yet reproduce every React behavior. The CLI is for explicit output and type checking.
+
+During Vite development, the compiler adds state identities for direct local
+`signal()` declarations. Pass a stable `HotContext` from `workstar/dev` to a
+root component when accepting Vite updates, as shown in the static starter.
+Production output does not include this instrumentation. The compiler maps
+script statements and the markup entry point back to authored source in Vite;
+individual markup expressions are not mapped yet.
 
 Inside `<script lang="ts">`, imports and an optional exported `Props` type define the component contract. Top-level `const`, `let`, and function declarations create state and behavior for each component instance; import `signal` from `workstar` for reactive local state. Keep module-wide shared state in an imported TypeScript module when sharing is intentional.
 
+Use `bind:attrs={record}` on a native element to spread a plain record of checked HTML attributes. The record can be reactive. Event handlers, styles, refs, and unsafe URLs are rejected; bind events explicitly with `on:event`.
+
 `<noscript>` accepts static text only. Put links and localized expressions elsewhere in the page; nested markup would be parsed as raw text and dynamic markers cannot hydrate reliably.
 
 See the [Workstar repository](https://github.com/wslab-ai/workstar) for starters and current limitations.
+
+For experimental React-style TSX and Vue SFC source conversion without their runtimes, see the [compatibility guide](https://github.com/wslab-ai/workstar/blob/main/docs/foreign-components.md). Use `?workstar` imports with the Vite plugin or `workstar-compile --compat` with any other build system.

package/bin/workstar-compile.mjs

@@ -2,8 +2,10 @@
 import { resolve } from 'node:path';
 import {
   compileViewFile,
+  compileForeignFile,
   compileViewDirectory,
   watchViewDirectory,
+  auditForeignDirectory,
 } from '../dist/src/project.js';
 
 const args = process.argv.slice(2);
@@ -13,7 +15,10 @@ try {
     (args.length === 4 && args[2] === '--css')
       ? { cssOutputPath: resolve(args.at(-1)) }
       : {};
-  if (
+  if (args.length === 2 && args[0] === '--compat-audit') {
+    const report = await auditForeignDirectory(resolve(args[1]));
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else if (
     (args.length === 3 || (args.length === 5 && args[3] === '--css')) &&
     args[0] === '--all'
   ) {
@@ -35,6 +40,13 @@ try {
     process.stdout.write(
       `Watching ${resolve(args[1])} for .workstar changes.\n`,
     );
+  } else if (
+    (args.length === 3 || (args.length === 5 && args[3] === '--css')) &&
+    args[0] === '--compat' &&
+    /\.(tsx|vue)$/.test(args[1] ?? '') &&
+    args[2]?.endsWith('.ts')
+  ) {
+    await compileForeignFile(resolve(args[1]), resolve(args[2]), cssOption);
   } else if (
     (args.length === 2 || (args.length === 4 && args[2] === '--css')) &&
     args[0]?.endsWith('.workstar') &&
@@ -45,7 +57,9 @@ try {
   } else {
     process.stderr.write(
       'Usage: workstar-compile input.workstar output.ts [--css public/components.css]\n' +
+        '       workstar-compile --compat input.tsx|input.vue output.ts [--css public/components.css]\n' +
         '       workstar-compile --all source-directory output-directory [--css public/components.css]\n' +
+        '       workstar-compile --compat-audit source-directory\n' +
         '       workstar-compile --watch source-directory output-directory [--css public/components.css]\n',
     );
     process.exitCode = 2;

package/dist/src/compat-rules.d.ts

@@ -0,0 +1,2 @@
+export declare const pathExpression: RegExp;
+export declare function reject(filename: string, reason: string): never;

package/dist/src/compat-rules.js

@@ -0,0 +1,4 @@
+export const pathExpression = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+export function reject(filename, reason) {
+    throw new Error(filename + ': unsupported compatibility syntax: ' + reason);
+}

package/dist/src/compat.d.ts

@@ -0,0 +1,5 @@
+export { convertReactComponent } from './react-compat.js';
+export { convertVueComponent } from './vue-compat.js';
+export declare function convertForeignComponent(source: string, filename: string, options?: {
+    resolveReactImport?: (specifier: string) => string | undefined;
+}): string;

package/dist/src/compat.js

@@ -0,0 +1,12 @@
+import { convertReactComponent } from './react-compat.js';
+import { convertVueComponent } from './vue-compat.js';
+import { reject } from './compat-rules.js';
+export { convertReactComponent } from './react-compat.js';
+export { convertVueComponent } from './vue-compat.js';
+export function convertForeignComponent(source, filename, options = {}) {
+    if (filename.endsWith('.tsx'))
+        return convertReactComponent(source, filename, options);
+    if (filename.endsWith('.vue'))
+        return convertVueComponent(source, filename);
+    return reject(filename, 'file extension');
+}

package/dist/src/component-script.d.ts

@@ -1,6 +1,14 @@
 import type { DefaultTreeAdapterTypes as Html } from 'parse5';
-export declare function componentScript(node: Html.Element, filename: string, componentImports: 'generated' | 'source', rewriteRelativeImport?: (specifier: string) => string): {
-    moduleScript: string;
-    setupScript: string;
+export interface ScriptStatement {
+    readonly code: string;
+    readonly sourceOffset?: number | undefined;
+    readonly exact?: boolean;
+}
+export declare function componentScript(node: Html.Element, filename: string, componentImports: 'generated' | 'source', sourcePosition: (offset: number) => {
+    line: number;
+    column: number;
+}, rewriteRelativeImport?: (specifier: string) => string, hotState?: boolean): {
+    moduleStatements: ScriptStatement[];
+    setupStatements: ScriptStatement[];
     props: string[];
 };

package/dist/src/component-script.js

@@ -1,15 +1,46 @@
 import ts from 'typescript';
-import { fail } from './errors.js';
-export function componentScript(node, filename, componentImports, rewriteRelativeImport) {
+import { ComponentCompileError } from './errors.js';
+function preserveLocalSignals(statement, file, signalBindings) {
+    const statementStart = statement.getStart(file);
+    let code = statement.getText(file);
+    const signals = statement.declarationList.declarations.flatMap((declaration) => {
+        const initializer = declaration.initializer;
+        if (!ts.isIdentifier(declaration.name) ||
+            !initializer ||
+            !ts.isCallExpression(initializer) ||
+            !ts.isIdentifier(initializer.expression) ||
+            !signalBindings.has(initializer.expression.text))
+            return [];
+        return [{ name: declaration.name.text, initializer }];
+    });
+    for (const { name, initializer } of signals.reverse()) {
+        const start = initializer.getStart(file) - statementStart;
+        const end = initializer.getEnd() - statementStart;
+        const original = code.slice(start, end);
+        const retained = `__context?.state(${JSON.stringify(`${name}:${original}`)}, () => ${original})`;
+        code =
+            code.slice(0, start) + `(${retained} ?? ${original})` + code.slice(end);
+    }
+    return signals.length > 0 ? code : undefined;
+}
+export function componentScript(node, filename, componentImports, sourcePosition, rewriteRelativeImport, hotState = false) {
     if (node.attrs.length !== 1 ||
         node.attrs[0]?.name !== 'lang' ||
         node.attrs[0].value !== 'ts') {
-        fail(filename, 'The component script must be <script lang="ts">.');
+        throw new ComponentCompileError('The component script must be <script lang="ts">.', filename, node.sourceCodeLocation
+            ? sourcePosition(node.sourceCodeLocation.startOffset)
+            : undefined);
     }
+    const scriptStart = node.sourceCodeLocation?.startTag?.endOffset;
+    const failAt = (message, offset = 0) => {
+        throw new ComponentCompileError(message, filename, scriptStart === undefined
+            ? undefined
+            : sourcePosition(scriptStart + offset));
+    };
     const script = node.childNodes
         .map((child) => {
         if (!('value' in child))
-            fail(filename, 'Invalid script content.');
+            return failAt('Invalid script content.');
         return child.value;
     })
         .join('');
@@ -18,90 +49,128 @@ export function componentScript(node, filename, componentImports, rewriteRelativ
         fileName: filename.replace(/\.workstar$/, '.ts'),
         reportDiagnostics: true,
     });
-    if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
-        fail(filename, 'Invalid TypeScript in component script.');
+    const syntaxError = syntax.diagnostics?.find((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (syntaxError) {
+        failAt(`Invalid TypeScript in component script: ${ts.flattenDiagnosticMessageText(syntaxError.messageText, ' ')}`, syntaxError.start ?? 0);
     }
     let props;
+    const signalBindings = new Set();
     const moduleStatements = [];
     const setupStatements = [];
     for (const statement of file.statements) {
         if (ts.isEmptyStatement(statement))
             continue;
+        const sourceOffset = scriptStart === undefined
+            ? undefined
+            : scriptStart + statement.getStart(file);
         if (ts.isImportDeclaration(statement)) {
             const specifier = ts.isStringLiteral(statement.moduleSpecifier)
                 ? statement.moduleSpecifier.text
                 : '';
+            const named = statement.importClause?.namedBindings;
+            if (specifier === 'workstar' && named && ts.isNamedImports(named)) {
+                for (const binding of named.elements) {
+                    if ((binding.propertyName ?? binding.name).text === 'signal') {
+                        signalBindings.add(binding.name.text);
+                    }
+                }
+            }
             if (specifier.endsWith('.workstar')) {
                 const binding = statement.importClause?.name?.text;
                 if (!/^(?:\.{1,2}\/)+(?:[A-Za-z0-9][\w-]*\/)*[A-Za-z0-9][\w-]*\.workstar$/.test(specifier) ||
                     !binding ||
                     statement.importClause?.isTypeOnly ||
                     statement.importClause?.namedBindings) {
-                    fail(filename, 'Import a relative .workstar view with a default import.');
+                    failAt('Import a relative .workstar view with a default import.', statement.getStart(file));
                 }
-                moduleStatements.push(`import { render as ${binding} } from '${componentImports === 'source' ? specifier : specifier.slice(0, -'.workstar'.length)}';`);
+                moduleStatements.push({
+                    code: `import { render as ${binding} } from '${componentImports === 'source' ? specifier : specifier.slice(0, -'.workstar'.length)}';`,
+                    sourceOffset,
+                });
             }
             else if (specifier.startsWith('.') && rewriteRelativeImport) {
                 const importText = statement.getText(file);
                 const start = statement.moduleSpecifier.getStart(file) - statement.getStart(file);
                 const end = statement.moduleSpecifier.getEnd() - statement.getStart(file);
-                moduleStatements.push(importText.slice(0, start) +
-                    JSON.stringify(rewriteRelativeImport(specifier)) +
-                    importText.slice(end));
+                moduleStatements.push({
+                    code: importText.slice(0, start) +
+                        JSON.stringify(rewriteRelativeImport(specifier)) +
+                        importText.slice(end),
+                    sourceOffset,
+                });
             }
             else {
-                moduleStatements.push(statement.getText(file));
+                moduleStatements.push({
+                    code: statement.getText(file),
+                    sourceOffset,
+                    exact: true,
+                });
             }
             continue;
         }
         if (ts.isInterfaceDeclaration(statement) &&
             statement.name.text === 'Props') {
             if (props)
-                fail(filename, 'The component can declare Props only once.');
+                failAt('The component can declare Props only once.', statement.getStart(file));
             props = statement.members.map((member) => {
                 if (!ts.isPropertySignature(member) ||
                     !member.name ||
                     !ts.isIdentifier(member.name)) {
-                    fail(filename, 'Props must use named properties.');
+                    return failAt('Props must use named properties.', member.getStart(file));
                 }
                 return member.name.text;
             });
-            moduleStatements.push(statement.getText(file));
+            moduleStatements.push({
+                code: statement.getText(file),
+                sourceOffset,
+                exact: true,
+            });
             continue;
         }
         if (ts.isTypeAliasDeclaration(statement) &&
             statement.name.text === 'Props' &&
             ts.isTypeLiteralNode(statement.type)) {
             if (props)
-                fail(filename, 'The component can declare Props only once.');
+                failAt('The component can declare Props only once.', statement.getStart(file));
             props = statement.type.members.map((member) => {
                 if (!ts.isPropertySignature(member) ||
                     !member.name ||
                     !ts.isIdentifier(member.name)) {
-                    fail(filename, 'Props must use named properties.');
+                    return failAt('Props must use named properties.', member.getStart(file));
                 }
                 return member.name.text;
             });
-            moduleStatements.push(statement.getText(file));
+            moduleStatements.push({
+                code: statement.getText(file),
+                sourceOffset,
+                exact: true,
+            });
             continue;
         }
         if (ts.isVariableStatement(statement) ||
             ts.isFunctionDeclaration(statement)) {
             if (statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
-                fail(filename, 'Component-local declarations cannot be exported.');
+                failAt('Component-local declarations cannot be exported.', statement.getStart(file));
             }
-            setupStatements.push(statement.getText(file));
+            const retained = hotState && ts.isVariableStatement(statement)
+                ? preserveLocalSignals(statement, file, signalBindings)
+                : undefined;
+            setupStatements.push({
+                code: retained ?? statement.getText(file),
+                sourceOffset,
+                exact: retained === undefined,
+            });
             continue;
         }
-        fail(filename, 'Only imports, Props, and component-local variables/functions are supported in the script.');
+        failAt('Only imports, Props, and component-local variables/functions are supported in the script.', statement.getStart(file));
     }
     if (!props) {
         props = [];
-        moduleStatements.push('type Props = Record<string, never>;');
+        moduleStatements.push({ code: 'type Props = Record<string, never>;' });
     }
     return {
-        moduleScript: moduleStatements.join('\n'),
-        setupScript: setupStatements.join('\n'),
+        moduleStatements,
+        setupStatements,
         props,
     };
 }

package/dist/src/control-elements.d.ts

@@ -2,6 +2,11 @@ export declare const controlAttribute = "data-workstar-compiler-control";
 export interface NormalizedControls {
     source: string;
     count: number;
+    originalOffset: (normalizedOffset: number) => number;
+}
+export declare class ControlSyntaxError extends Error {
+    readonly offset: number;
+    constructor(message: string, offset: number);
 }
 /** Adapt authoring controls to HTML parser insertion modes, including select and table. */
 export declare function normalizeControls(source: string): NormalizedControls;

package/dist/src/control-elements.js

@@ -1,5 +1,13 @@
 const controlNames = new Set(['Each', 'If', 'Else', 'Use']);
 export const controlAttribute = 'data-workstar-compiler-control';
+export class ControlSyntaxError extends Error {
+    offset;
+    constructor(message, offset) {
+        super(message);
+        this.offset = offset;
+        this.name = 'ControlSyntaxError';
+    }
+}
 function tagEnd(source, start) {
     let quote;
     for (let index = start + 1; index < source.length; index++) {
@@ -15,19 +23,28 @@ function tagEnd(source, start) {
             return index;
         }
     }
-    throw new Error('Unclosed HTML tag.');
+    throw new ControlSyntaxError('Unclosed HTML tag.', start);
 }
 /** Adapt authoring controls to HTML parser insertion modes, including select and table. */
 export function normalizeControls(source) {
     if (source.includes(controlAttribute)) {
-        throw new Error(`${controlAttribute} is reserved for the compiler.`);
+        throw new ControlSyntaxError(`${controlAttribute} is reserved for the compiler.`, source.indexOf(controlAttribute));
     }
-    const scriptEnd = /<\/script\s*>/i.exec(source);
-    const start = scriptEnd ? scriptEnd.index + scriptEnd[0].length : 0;
-    let result = source.slice(0, start);
-    let cursor = start;
+    let result = '';
+    let cursor = 0;
     let count = 0;
     const stack = [];
+    const replacements = [];
+    const appendReplacement = (authoredStart, authoredEnd, replacement) => {
+        const generatedStart = result.length;
+        result += replacement;
+        replacements.push({
+            generatedStart,
+            generatedEnd: result.length,
+            authoredStart,
+            authoredEnd,
+        });
+    };
     while (cursor < source.length) {
         const opening = source.indexOf('<', cursor);
         if (opening < 0)
@@ -36,7 +53,7 @@ export function normalizeControls(source) {
         if (source.startsWith('<!--', opening)) {
             const end = source.indexOf('-->', opening + 4);
             if (end < 0)
-                throw new Error('Unclosed HTML comment.');
+                throw new ControlSyntaxError('Unclosed HTML comment.', opening);
             result += source.slice(opening, end + 3);
             cursor = end + 3;
             continue;
@@ -48,8 +65,9 @@ export function normalizeControls(source) {
         if (!name || !controlNames.has(name)) {
             result += tag;
             cursor = end + 1;
-            if (/^<textarea(?=[\s>])/i.test(tag)) {
-                const closing = /<\/textarea\s*>/gi;
+            const rawTextTag = /^<(script|style|textarea)(?=[\s>])/i.exec(tag)?.[1];
+            if (rawTextTag) {
+                const closing = new RegExp(`</${rawTextTag}\\s*>`, 'gi');
                 closing.lastIndex = cursor;
                 const close = closing.exec(source);
                 if (close) {
@@ -62,31 +80,48 @@ export function normalizeControls(source) {
         const closing = match[1] === '/';
         const selfClosing = /\/\s*>$/.test(tag);
         if (closing) {
-            if (stack.pop() !== name) {
-                throw new Error(`Mismatched </${name}> control element.`);
+            if (stack.pop()?.name !== name) {
+                throw new ControlSyntaxError(`Mismatched </${name}> control element.`, opening);
             }
-            result += '</template>';
+            appendReplacement(opening, end + 1, '</template>');
         }
         else {
             if (selfClosing && name !== 'Use') {
-                throw new Error(`<${name}> cannot be self-closing.`);
+                throw new ControlSyntaxError(`<${name}> cannot be self-closing.`, opening);
             }
             const authoredAttributes = tag.slice(match[0].length, -1);
             const attributes = selfClosing
                 ? authoredAttributes.replace(/\/\s*$/, '')
                 : authoredAttributes;
-            result += `<template ${controlAttribute}="${name}"${attributes}>`;
-            if (selfClosing)
-                result += '</template>';
-            else
-                stack.push(name);
+            appendReplacement(opening, end + 1, `<template ${controlAttribute}="${name}"${attributes}>${selfClosing ? '</template>' : ''}`);
+            if (!selfClosing)
+                stack.push({ name, offset: opening });
             count++;
         }
         cursor = end + 1;
     }
     result += source.slice(cursor);
     if (stack.length > 0) {
-        throw new Error(`Unclosed <${stack.at(-1)}> control element.`);
+        const unclosed = stack.at(-1);
+        throw new ControlSyntaxError(`Unclosed <${unclosed.name}> control element.`, unclosed.offset);
     }
-    return { source: result, count };
+    return {
+        source: result,
+        count,
+        originalOffset(normalizedOffset) {
+            let difference = 0;
+            for (const replacement of replacements) {
+                if (normalizedOffset < replacement.generatedStart)
+                    break;
+                if (normalizedOffset < replacement.generatedEnd) {
+                    return replacement.authoredStart;
+                }
+                difference +=
+                    replacement.generatedEnd -
+                        replacement.generatedStart -
+                        (replacement.authoredEnd - replacement.authoredStart);
+            }
+            return normalizedOffset - difference;
+        },
+    };
 }

package/dist/src/errors.d.ts

@@ -1,5 +1,13 @@
 export declare class ComponentCompileError extends Error {
+    readonly description: string;
     readonly filename: string;
-    constructor(message: string, filename: string);
+    readonly position?: {
+        readonly line: number;
+        readonly column: number;
+    } | undefined;
+    constructor(description: string, filename: string, position?: {
+        readonly line: number;
+        readonly column: number;
+    } | undefined);
 }
 export declare function fail(filename: string, message: string): never;

package/dist/src/errors.js

@@ -1,8 +1,12 @@
 export class ComponentCompileError extends Error {
+    description;
     filename;
-    constructor(message, filename) {
-        super(`${filename}: ${message}`);
+    position;
+    constructor(description, filename, position) {
+        super(`${filename}${position ? `:${position.line}:${position.column}` : ''}: ${description}`);
+        this.description = description;
         this.filename = filename;
+        this.position = position;
         this.name = 'ComponentCompileError';
     }
 }

package/dist/src/index.d.ts

@@ -1,16 +1,20 @@
+import { type SourceOrigin } from './source-origin.js';
 export { ComponentCompileError } from './errors.js';
 /** Compile a typed component and its optional co-located stylesheet. */
 export declare function compileComponentParts(source: string, filename?: string, options?: {
     componentImports?: 'generated' | 'source';
     rewriteRelativeImport?: (specifier: string) => string;
     cssImport?: string;
+    hotState?: boolean;
 }): {
     code: string;
     css: string;
+    origins: SourceOrigin[];
 };
 /** Compile a component to a TypeScript module; use parts to emit its CSS. */
 export declare function compileComponent(source: string, filename?: string, options?: {
     componentImports?: 'generated' | 'source';
     rewriteRelativeImport?: (specifier: string) => string;
     cssImport?: string;
+    hotState?: boolean;
 }): string;