workstar-compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workstar Lab
+
+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

@@ -0,0 +1,19 @@
+# Workstar compiler
+
+The `.workstar` component compiler, command-line checker, and optional Vite plugin for Workstar applications.
+
+Use the compiler with a matching Workstar version and validate a project with `npm run check` before building. A component can live in any directory under the configured source root; generated type-checking files belong outside authored `src`.
+
+The `workstar-compile` command compiles one component or a directory:
+
+```sh
+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.
+
+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.
+
+`<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.

package/bin/workstar-compile.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import {
+  compileViewFile,
+  compileViewDirectory,
+  watchViewDirectory,
+} from '../dist/src/project.js';
+
+const args = process.argv.slice(2);
+try {
+  const cssOption =
+    (args.length === 5 && args[3] === '--css') ||
+    (args.length === 4 && args[2] === '--css')
+      ? { cssOutputPath: resolve(args.at(-1)) }
+      : {};
+  if (
+    (args.length === 3 || (args.length === 5 && args[3] === '--css')) &&
+    args[0] === '--all'
+  ) {
+    await compileViewDirectory(resolve(args[1]), resolve(args[2]), cssOption);
+  } else if (
+    (args.length === 3 || (args.length === 5 && args[3] === '--css')) &&
+    args[0] === '--watch'
+  ) {
+    await watchViewDirectory(
+      resolve(args[1]),
+      resolve(args[2]),
+      (error) => {
+        process.stderr.write(
+          `${error instanceof Error ? error.message : String(error)}\n`,
+        );
+      },
+      cssOption,
+    );
+    process.stdout.write(
+      `Watching ${resolve(args[1])} for .workstar changes.\n`,
+    );
+  } else if (
+    (args.length === 2 || (args.length === 4 && args[2] === '--css')) &&
+    args[0]?.endsWith('.workstar') &&
+    args[1]?.endsWith('.ts')
+  ) {
+    const [input, output] = args;
+    await compileViewFile(resolve(input), resolve(output), cssOption);
+  } else {
+    process.stderr.write(
+      'Usage: workstar-compile input.workstar output.ts [--css public/components.css]\n' +
+        '       workstar-compile --all source-directory output-directory [--css public/components.css]\n' +
+        '       workstar-compile --watch source-directory output-directory [--css public/components.css]\n',
+    );
+    process.exitCode = 2;
+  }
+} catch (error) {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,6 @@
+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;
+    props: string[];
+};

package/dist/src/component-script.js

@@ -0,0 +1,107 @@
+import ts from 'typescript';
+import { fail } from './errors.js';
+export function componentScript(node, filename, componentImports, rewriteRelativeImport) {
+    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">.');
+    }
+    const script = node.childNodes
+        .map((child) => {
+        if (!('value' in child))
+            fail(filename, 'Invalid script content.');
+        return child.value;
+    })
+        .join('');
+    const file = ts.createSourceFile(filename, script, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const syntax = ts.transpileModule(script, {
+        fileName: filename.replace(/\.workstar$/, '.ts'),
+        reportDiagnostics: true,
+    });
+    if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
+        fail(filename, 'Invalid TypeScript in component script.');
+    }
+    let props;
+    const moduleStatements = [];
+    const setupStatements = [];
+    for (const statement of file.statements) {
+        if (ts.isEmptyStatement(statement))
+            continue;
+        if (ts.isImportDeclaration(statement)) {
+            const specifier = ts.isStringLiteral(statement.moduleSpecifier)
+                ? statement.moduleSpecifier.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.');
+                }
+                moduleStatements.push(`import { render as ${binding} } from '${componentImports === 'source' ? specifier : specifier.slice(0, -'.workstar'.length)}';`);
+            }
+            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));
+            }
+            else {
+                moduleStatements.push(statement.getText(file));
+            }
+            continue;
+        }
+        if (ts.isInterfaceDeclaration(statement) &&
+            statement.name.text === 'Props') {
+            if (props)
+                fail(filename, 'The component can declare Props only once.');
+            props = statement.members.map((member) => {
+                if (!ts.isPropertySignature(member) ||
+                    !member.name ||
+                    !ts.isIdentifier(member.name)) {
+                    fail(filename, 'Props must use named properties.');
+                }
+                return member.name.text;
+            });
+            moduleStatements.push(statement.getText(file));
+            continue;
+        }
+        if (ts.isTypeAliasDeclaration(statement) &&
+            statement.name.text === 'Props' &&
+            ts.isTypeLiteralNode(statement.type)) {
+            if (props)
+                fail(filename, 'The component can declare Props only once.');
+            props = statement.type.members.map((member) => {
+                if (!ts.isPropertySignature(member) ||
+                    !member.name ||
+                    !ts.isIdentifier(member.name)) {
+                    fail(filename, 'Props must use named properties.');
+                }
+                return member.name.text;
+            });
+            moduleStatements.push(statement.getText(file));
+            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.');
+            }
+            setupStatements.push(statement.getText(file));
+            continue;
+        }
+        fail(filename, 'Only imports, Props, and component-local variables/functions are supported in the script.');
+    }
+    if (!props) {
+        props = [];
+        moduleStatements.push('type Props = Record<string, never>;');
+    }
+    return {
+        moduleScript: moduleStatements.join('\n'),
+        setupScript: setupStatements.join('\n'),
+        props,
+    };
+}

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

@@ -0,0 +1,7 @@
+export declare const controlAttribute = "data-workstar-compiler-control";
+export interface NormalizedControls {
+    source: string;
+    count: 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

@@ -0,0 +1,92 @@
+const controlNames = new Set(['Each', 'If', 'Else', 'Use']);
+export const controlAttribute = 'data-workstar-compiler-control';
+function tagEnd(source, start) {
+    let quote;
+    for (let index = start + 1; index < source.length; index++) {
+        const character = source[index];
+        if (quote) {
+            if (character === quote)
+                quote = undefined;
+        }
+        else if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (character === '>') {
+            return index;
+        }
+    }
+    throw new Error('Unclosed HTML tag.');
+}
+/** 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.`);
+    }
+    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 count = 0;
+    const stack = [];
+    while (cursor < source.length) {
+        const opening = source.indexOf('<', cursor);
+        if (opening < 0)
+            break;
+        result += source.slice(cursor, opening);
+        if (source.startsWith('<!--', opening)) {
+            const end = source.indexOf('-->', opening + 4);
+            if (end < 0)
+                throw new Error('Unclosed HTML comment.');
+            result += source.slice(opening, end + 3);
+            cursor = end + 3;
+            continue;
+        }
+        const end = tagEnd(source, opening);
+        const tag = source.slice(opening, end + 1);
+        const match = /^<\s*(\/?)\s*([A-Za-z][\w:-]*)(?=[\s/>])/.exec(tag);
+        const name = match?.[2];
+        if (!name || !controlNames.has(name)) {
+            result += tag;
+            cursor = end + 1;
+            if (/^<textarea(?=[\s>])/i.test(tag)) {
+                const closing = /<\/textarea\s*>/gi;
+                closing.lastIndex = cursor;
+                const close = closing.exec(source);
+                if (close) {
+                    result += source.slice(cursor, close.index + close[0].length);
+                    cursor = close.index + close[0].length;
+                }
+            }
+            continue;
+        }
+        const closing = match[1] === '/';
+        const selfClosing = /\/\s*>$/.test(tag);
+        if (closing) {
+            if (stack.pop() !== name) {
+                throw new Error(`Mismatched </${name}> control element.`);
+            }
+            result += '</template>';
+        }
+        else {
+            if (selfClosing && name !== 'Use') {
+                throw new Error(`<${name}> cannot be self-closing.`);
+            }
+            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);
+            count++;
+        }
+        cursor = end + 1;
+    }
+    result += source.slice(cursor);
+    if (stack.length > 0) {
+        throw new Error(`Unclosed <${stack.at(-1)}> control element.`);
+    }
+    return { source: result, count };
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class ComponentCompileError extends Error {
+    readonly filename: string;
+    constructor(message: string, filename: string);
+}
+export declare function fail(filename: string, message: string): never;

package/dist/src/errors.js

@@ -0,0 +1,11 @@
+export class ComponentCompileError extends Error {
+    filename;
+    constructor(message, filename) {
+        super(`${filename}: ${message}`);
+        this.filename = filename;
+        this.name = 'ComponentCompileError';
+    }
+}
+export function fail(filename, message) {
+    throw new ComponentCompileError(message, filename);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+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;
+}): {
+    code: string;
+    css: string;
+};
+/** 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;
+}): string;

package/dist/src/index.js

@@ -0,0 +1,415 @@
+import { parseFragment } from 'parse5';
+import { componentScript } from './component-script.js';
+import { controlAttribute, normalizeControls } from './control-elements.js';
+import { fail } from './errors.js';
+import { compileStyle } from './styles.js';
+export { ComponentCompileError } from './errors.js';
+const pathExpression = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*|\[\d+\])*$/;
+const identifier = /^[A-Za-z_$][\w$]*$/;
+const urlAttributes = new Set([
+    'href',
+    'src',
+    'action',
+    'formaction',
+    'xlink:href',
+]);
+const voidElements = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        const entities = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#39;',
+        };
+        return entities[character] ?? character;
+    });
+}
+function escapeTemplate(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/`/g, '\\`')
+        .replace(/\$\{/g, '\\${');
+}
+function controlName(node) {
+    return node.attrs.find((attribute) => attribute.name === controlAttribute)
+        ?.value;
+}
+function elementChildren(node) {
+    return node.tagName === 'template'
+        ? node.content.childNodes
+        : node.childNodes;
+}
+function expression(value, filename, locals) {
+    if (!pathExpression.test(value))
+        fail(filename, `Unsupported expression: ${value}`);
+    const root = /^[A-Za-z_$][\w$]*/.exec(value)?.[0];
+    if (!root)
+        fail(filename, `Unsupported expression: ${value}`);
+    const local = locals.get(root);
+    return local ? local + value.slice(root.length) : value;
+}
+function dynamicAttribute(value, filename, locals) {
+    if (!value.startsWith('{') && !value.endsWith('}'))
+        return null;
+    if (!value.startsWith('{') || !value.endsWith('}')) {
+        fail(filename, `Invalid attribute expression: ${value}`);
+    }
+    return expression(value.slice(1, -1).trim(), filename, locals);
+}
+function textMarkup(value, filename, locals) {
+    let result = '';
+    let start = 0;
+    const pattern = /\{([^{}]+)\}/g;
+    for (const match of value.matchAll(pattern)) {
+        const index = match.index;
+        const staticText = value.slice(start, index);
+        if (/[{}]/.test(staticText))
+            fail(filename, 'Invalid text expression.');
+        result += escapeTemplate(escapeHtml(staticText));
+        result += '${() => ' + expression(match[1].trim(), filename, locals) + '}';
+        start = index + match[0].length;
+    }
+    const remaining = value.slice(start);
+    if (/[{}]/.test(remaining))
+        fail(filename, 'Invalid text expression.');
+    return result + escapeTemplate(escapeHtml(remaining));
+}
+function childMarkup(children, filename, locals, source) {
+    return children
+        .map((child) => nodeMarkup(child, filename, locals, source))
+        .join('');
+}
+function assertControlElementsPreserved(authoredCount, body, filename) {
+    let parsed = 0;
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (!('tagName' in node))
+                continue;
+            if (controlName(node))
+                parsed++;
+            visit(elementChildren(node));
+        }
+    };
+    visit(body);
+    if (parsed !== authoredCount) {
+        fail(filename, 'A control element was discarded by the HTML parser in this context.');
+    }
+}
+function scopeMarkupElements(nodes, attribute, filename) {
+    for (const node of nodes) {
+        if (!('tagName' in node))
+            continue;
+        if (node.tagName !== 'template') {
+            if (node.attrs.some((entry) => entry.name === attribute)) {
+                fail(filename, `${attribute} is reserved for component styles.`);
+            }
+            node.attrs.push({ name: attribute, value: '' });
+        }
+        scopeMarkupElements(elementChildren(node), attribute, filename);
+    }
+}
+function eachMarkup(node, filename, locals, sourceText) {
+    const attributes = new Map(node.attrs
+        .filter((attribute) => attribute.name !== controlAttribute)
+        .map((attribute) => [attribute.name, attribute.value]));
+    if (attributes.size !== 3 ||
+        !attributes.has('each') ||
+        !attributes.has('as') ||
+        !attributes.has('key')) {
+        fail(filename, '<Each> needs each={path}, as="name", and key="field|self".');
+    }
+    const source = dynamicAttribute(attributes.get('each'), filename, locals);
+    const name = attributes.get('as');
+    const key = attributes.get('key');
+    if (!source || !identifier.test(name))
+        fail(filename, 'Invalid <Each> binding.');
+    if (key !== 'self' && !identifier.test(key))
+        fail(filename, '<Each> key must be a field name or "self".');
+    const nested = new Map(locals);
+    nested.set(name, `${name}.value`);
+    const body = childMarkup(elementChildren(node), filename, nested, sourceText);
+    const keyExpression = key === 'self' ? name : `${name}.${key}`;
+    return ('${__repeat(() => ' +
+        source +
+        ', (' +
+        name +
+        ') => ' +
+        keyExpression +
+        ', (' +
+        name +
+        ') => __html`' +
+        body +
+        '`)}');
+}
+function ifMarkup(node, filename, locals, source) {
+    const attributes = node.attrs.filter((attribute) => attribute.name !== controlAttribute);
+    if (attributes.length !== 1 || attributes[0]?.name !== 'when') {
+        fail(filename, '<If> needs exactly when={path}.');
+    }
+    const condition = dynamicAttribute(attributes[0].value, filename, locals);
+    if (!condition)
+        fail(filename, '<If> needs a condition expression.');
+    const children = elementChildren(node);
+    const elseIndex = children.findIndex((child) => 'tagName' in child && controlName(child) === 'Else');
+    const before = elseIndex < 0 ? children : children.slice(0, elseIndex);
+    let alternate = 'null';
+    if (elseIndex >= 0) {
+        const elseNode = children[elseIndex];
+        if (!elseNode ||
+            !('tagName' in elseNode) ||
+            elseNode.attrs.some((attribute) => attribute.name !== controlAttribute)) {
+            fail(filename, '<Else> cannot have attributes.');
+        }
+        if (children
+            .slice(elseIndex + 1)
+            .some((child) => !('value' in child) || child.value.trim() !== '')) {
+            fail(filename, '<Else> must be the last child of <If>.');
+        }
+        alternate =
+            '__html`' +
+                childMarkup(elementChildren(elseNode), filename, locals, source) +
+                '`';
+    }
+    const truthy = '__html`' + childMarkup(before, filename, locals, source) + '`';
+    return '${() => (' + condition + ' ? ' + truthy + ' : ' + alternate + ')}';
+}
+function originalAttributeName(node, name, source) {
+    const location = node.sourceCodeLocation?.attrs?.[name];
+    if (!location)
+        return name;
+    return /^([^\s=/>]+)/.exec(source.slice(location.startOffset))?.[1] ?? name;
+}
+function componentMarkup(node, filename, locals, source) {
+    const children = elementChildren(node);
+    const hasChildren = children.some((child) => !('value' in child) || child.value.trim());
+    const binding = node.attrs.find((attribute) => attribute.name === 'component');
+    if (!binding)
+        fail(filename, '<Use> needs component={ImportedView}.');
+    const renderer = dynamicAttribute(binding.value, filename, locals);
+    if (!renderer)
+        fail(filename, '<Use> needs a component expression.');
+    const props = node.attrs
+        .filter((attribute) => attribute !== binding && attribute.name !== controlAttribute)
+        .map((attribute) => {
+        const name = originalAttributeName(node, attribute.name, source);
+        if (!identifier.test(name)) {
+            fail(filename, `<Use> prop ${name} must be a TypeScript identifier.`);
+        }
+        const value = dynamicAttribute(attribute.value, filename, locals);
+        const authored = node.sourceCodeLocation?.attrs?.[attribute.name];
+        const raw = authored
+            ? source.slice(authored.startOffset, authored.endOffset)
+            : '';
+        const output = value ?? (raw.includes('=') ? JSON.stringify(attribute.value) : 'true');
+        return `${name}: ${output}`;
+    });
+    if (hasChildren) {
+        if (node.attrs.some((attribute) => attribute.name === 'children')) {
+            fail(filename, '<Use> cannot set children twice.');
+        }
+        props.push('children: __html`' +
+            childMarkup(children, filename, locals, source) +
+            '`');
+    }
+    return '${() => ' + renderer + '({' + props.join(', ') + '})}';
+}
+function elementMarkup(node, filename, locals, source) {
+    if (!node.sourceCodeLocation)
+        fail(filename, 'HTML parser inserted an implicit element.');
+    const tag = node.tagName;
+    if (tag === 'template') {
+        switch (controlName(node)) {
+            case 'Each':
+                return eachMarkup(node, filename, locals, source);
+            case 'If':
+                return ifMarkup(node, filename, locals, source);
+            case 'Else':
+                fail(filename, '<Else> must be inside <If>.');
+            case 'Use':
+                return componentMarkup(node, filename, locals, source);
+            default:
+                fail(filename, '<template> is not supported in component markup yet.');
+        }
+    }
+    if (/^(script|style|title)$/.test(tag)) {
+        fail(filename, `<${tag}> is not supported in component markup yet.`);
+    }
+    if (tag === 'noscript' &&
+        node.childNodes.some((child) => !('value' in child) ||
+            /\{[^{}]+\}|<\s*\/?\s*[a-z][^>]*>/i.test(child.value))) {
+        fail(filename, '<noscript> supports static text only; place links and expressions outside it.');
+    }
+    let result = `<${tag}`;
+    for (const attribute of node.attrs) {
+        const name = attribute.name;
+        if (tag === 'textarea' && name === 'value') {
+            fail(filename, '<textarea> value belongs in element content.');
+        }
+        if (name === 'srcdoc')
+            fail(filename, 'srcdoc is not supported.');
+        if (/^on/i.test(name) && !name.startsWith('on:')) {
+            fail(filename, `Use on:event instead of ${name}.`);
+        }
+        const value = dynamicAttribute(attribute.value, filename, locals);
+        if (name.startsWith('on:')) {
+            if (!value)
+                fail(filename, `${name} needs a handler expression.`);
+            result += '${__on(' + JSON.stringify(name.slice(3)) + ', ' + value + ')}';
+        }
+        else if (value) {
+            result += '${__attr(' + JSON.stringify(name) + ', () => ' + value + ')}';
+        }
+        else if (urlAttributes.has(name)) {
+            result +=
+                '${__attr(' +
+                    JSON.stringify(name) +
+                    ', ' +
+                    JSON.stringify(attribute.value) +
+                    ')}';
+        }
+        else {
+            result += ` ${name}="${escapeTemplate(escapeHtml(attribute.value))}"`;
+        }
+    }
+    if (tag === 'textarea') {
+        const content = node.childNodes
+            .map((child) => {
+            if (!('value' in child)) {
+                fail(filename, '<textarea> can contain text only.');
+            }
+            return child.value;
+        })
+            .join('');
+        const dynamic = /^\s*\{([^{}]+)\}\s*$/.exec(content);
+        if (dynamic) {
+            const source = expression(dynamic[1].trim(), filename, locals);
+            return result + '${__textareaValue(() => ' + source + ')}></textarea>';
+        }
+        if (/[{}]/.test(content)) {
+            fail(filename, '<textarea> needs one {path} expression or static text.');
+        }
+        return result + '>' + escapeTemplate(escapeHtml(content)) + '</textarea>';
+    }
+    result += '>';
+    if (voidElements.has(tag)) {
+        if (node.childNodes.length > 0)
+            fail(filename, `<${tag}> cannot have children.`);
+        return result;
+    }
+    return (result +
+        childMarkup(node.childNodes, filename, locals, source) +
+        `</${tag}>`);
+}
+function nodeMarkup(node, filename, locals, source) {
+    if ('tagName' in node)
+        return elementMarkup(node, filename, locals, source);
+    if ('value' in node)
+        return textMarkup(node.value, filename, locals);
+    if ('data' in node)
+        return `<!--${escapeTemplate(node.data)}-->`;
+    return fail(filename, 'Doctype belongs in the document shell.');
+}
+/** Compile a typed component and its optional co-located stylesheet. */
+export function compileComponentParts(source, filename = 'Component.workstar', options = {}) {
+    let normalized;
+    try {
+        normalized = normalizeControls(source);
+    }
+    catch (error) {
+        fail(filename, error instanceof Error ? error.message : String(error));
+    }
+    const normalizedSource = normalized.source;
+    const errors = [];
+    const fragment = parseFragment(normalizedSource, {
+        sourceCodeLocationInfo: true,
+        onParseError: (error) => errors.push(`${error.code} at ${error.startLine}:${error.startCol}`),
+    });
+    if (errors.length > 0)
+        fail(filename, errors[0]);
+    const content = fragment.childNodes.filter((node) => !('value' in node) || node.value.trim().length > 0);
+    const first = content[0];
+    const hasScript = first && 'tagName' in first && first.tagName === 'script';
+    if (!hasScript &&
+        content.some((node) => 'tagName' in node && node.tagName === 'script')) {
+        fail(filename, 'A <script lang="ts"> block must come first.');
+    }
+    const { moduleScript, setupScript, props } = hasScript
+        ? componentScript(first, filename, options.componentImports ?? 'generated', options.rewriteRelativeImport)
+        : {
+            moduleScript: 'export type Props = Record<string, never>;',
+            setupScript: '',
+            props: [],
+        };
+    const componentBody = hasScript ? content.slice(1) : content;
+    const last = componentBody.at(-1);
+    const hasStyle = last && 'tagName' in last && last.tagName === 'style';
+    const markup = hasStyle ? componentBody.slice(0, -1) : componentBody;
+    if (markup.some((node) => 'tagName' in node && node.tagName === 'style')) {
+        fail(filename, 'A single <style> block must come last.');
+    }
+    let css = '';
+    if (hasStyle) {
+        const global = last.attrs.length === 1 &&
+            last.attrs[0]?.name === 'global' &&
+            last.attrs[0].value === '';
+        if (last.attrs.length > 0 && !global) {
+            fail(filename, 'Use <style> or <style global> only.');
+        }
+        const authoredCss = last.childNodes
+            .map((child) => {
+            if (!('value' in child))
+                fail(filename, 'Invalid <style> content.');
+            return child.value;
+        })
+            .join('');
+        try {
+            const style = compileStyle(authoredCss, filename, global);
+            css = style.css;
+            if (style.scopeAttribute) {
+                scopeMarkupElements(markup, style.scopeAttribute, filename);
+            }
+        }
+        catch (error) {
+            fail(filename, error instanceof Error ? error.message : String(error));
+        }
+    }
+    assertControlElementsPreserved(normalized.count, markup, filename);
+    const body = childMarkup(markup, filename, new Map(), normalizedSource);
+    if (body.trim().length === 0)
+        fail(filename, 'The component has no markup.');
+    const destructure = props.length > 0 ? `  const { ${props.join(', ')} } = props;\n` : '';
+    const code = [
+        '// Generated by workstar-compiler. Edit the .workstar source instead.',
+        "import { html as __html, attr as __attr, on as __on, repeat as __repeat, textareaValue as __textareaValue } from 'workstar';",
+        ...(css && options.cssImport
+            ? [`import ${JSON.stringify(options.cssImport)};`]
+            : []),
+        moduleScript,
+        'export function render(props: Props) {',
+        destructure + setupScript + '\n  return __html`' + body + '`;',
+        '}',
+        '',
+    ].join('\n');
+    return { code, css };
+}
+/** Compile a component to a TypeScript module; use parts to emit its CSS. */
+export function compileComponent(source, filename = 'Component.workstar', options = {}) {
+    return compileComponentParts(source, filename, options).code;
+}

package/dist/src/project.d.ts

@@ -0,0 +1,9 @@
+export interface ProjectStyles {
+    cssOutputPath?: string;
+}
+/** Compile one authored view without rewriting unrelated generated modules. */
+export declare function compileViewFile(sourcePath: string, outputPath: string, options?: ProjectStyles): Promise<void>;
+/** Compile every view before writing any generated modules. */
+export declare function compileViewDirectory(sourceDirectory: string, outputDirectory: string, options?: ProjectStyles): Promise<string[]>;
+/** Watch a view directory and recompile changed views for local development. */
+export declare function watchViewDirectory(sourceDirectory: string, outputDirectory: string, onError: (error: unknown) => void, options?: ProjectStyles): Promise<() => void>;

package/dist/src/project.js

@@ -0,0 +1,123 @@
+import { watch } from 'node:fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { compileComponentParts } from './index.js';
+async function filesInDirectory(directory, include, prefix = '') {
+    const entries = await readdir(join(directory, prefix), {
+        withFileTypes: true,
+    });
+    const paths = await Promise.all(entries.map(async (entry) => {
+        const path = join(prefix, entry.name);
+        if (entry.isDirectory())
+            return filesInDirectory(directory, include, path);
+        return entry.isFile() && include(entry.name) ? [path] : [];
+    }));
+    return paths.flat().sort();
+}
+function generatedPath(viewPath) {
+    return `${viewPath.slice(0, -'.workstar'.length)}.ts`;
+}
+function relocatedImport(sourcePath, outputPath, specifier) {
+    const target = resolve(dirname(sourcePath), specifier);
+    const path = relative(dirname(outputPath), target).split(sep).join('/');
+    return path.startsWith('.') ? path : `./${path}`;
+}
+/** Compile one authored view without rewriting unrelated generated modules. */
+export async function compileViewFile(sourcePath, outputPath, options = {}) {
+    const source = await readFile(sourcePath, 'utf8');
+    const { code, css } = compileComponentParts(source, sourcePath, {
+        rewriteRelativeImport: (specifier) => relocatedImport(sourcePath, outputPath, specifier),
+    });
+    if (css && !options.cssOutputPath) {
+        throw new Error(`${sourcePath}: pass cssOutputPath to emit component styles.`);
+    }
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, code, 'utf8');
+    if (options.cssOutputPath) {
+        await mkdir(dirname(options.cssOutputPath), { recursive: true });
+        await writeFile(options.cssOutputPath, css, 'utf8');
+    }
+}
+/** Compile every view before writing any generated modules. */
+export async function compileViewDirectory(sourceDirectory, outputDirectory, options = {}) {
+    const viewPaths = await filesInDirectory(sourceDirectory, (name) => name.endsWith('.workstar'));
+    if (viewPaths.length === 0) {
+        throw new Error(`No .workstar views found in ${sourceDirectory}.`);
+    }
+    const modules = await Promise.all(viewPaths.map(async (viewPath) => {
+        const sourcePath = join(sourceDirectory, viewPath);
+        const outputPath = join(outputDirectory, generatedPath(viewPath));
+        const source = await readFile(sourcePath, 'utf8');
+        const { code, css } = compileComponentParts(source, sourcePath, {
+            rewriteRelativeImport: (specifier) => relocatedImport(sourcePath, outputPath, specifier),
+        });
+        return {
+            filename: generatedPath(viewPath),
+            code,
+            css,
+        };
+    }));
+    if (modules.some(({ css }) => css) && !options.cssOutputPath) {
+        throw new Error('Pass cssOutputPath to emit component styles.');
+    }
+    await mkdir(outputDirectory, { recursive: true });
+    const current = new Set(modules.map(({ filename }) => filename));
+    for (const path of await filesInDirectory(outputDirectory, (name) => name.endsWith('.ts'))) {
+        if (current.has(path))
+            continue;
+        const stalePath = join(outputDirectory, path);
+        if ((await readFile(stalePath, 'utf8')).startsWith('// Generated by workstar-compiler.')) {
+            await rm(stalePath);
+        }
+    }
+    await Promise.all(modules.map(async ({ filename, code }) => {
+        const outputPath = join(outputDirectory, filename);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, code, 'utf8');
+    }));
+    if (options.cssOutputPath) {
+        const stylesheet = modules
+            .filter(({ css }) => css)
+            .map(({ filename, css }) => `/* ${filename} */\n${css}`)
+            .join('\n');
+        await mkdir(dirname(options.cssOutputPath), { recursive: true });
+        await writeFile(options.cssOutputPath, stylesheet, 'utf8');
+    }
+    return modules.map(({ filename }) => filename);
+}
+/** Watch a view directory and recompile changed views for local development. */
+export async function watchViewDirectory(sourceDirectory, outputDirectory, onError, options = {}) {
+    await compileViewDirectory(sourceDirectory, outputDirectory, options);
+    let debounce;
+    let compiling = false;
+    let pending = false;
+    async function recompile() {
+        if (compiling) {
+            pending = true;
+            return;
+        }
+        compiling = true;
+        do {
+            pending = false;
+            try {
+                await compileViewDirectory(sourceDirectory, outputDirectory, options);
+            }
+            catch (error) {
+                onError(error);
+            }
+        } while (pending);
+        compiling = false;
+    }
+    const watcher = watch(sourceDirectory, { recursive: true }, (_event, filename) => {
+        if (filename && !filename.endsWith('.workstar'))
+            return;
+        if (debounce)
+            clearTimeout(debounce);
+        debounce = setTimeout(() => void recompile(), 60);
+    });
+    return () => {
+        if (debounce)
+            clearTimeout(debounce);
+        watcher.close();
+    };
+}

package/dist/src/styles.d.ts

@@ -0,0 +1,6 @@
+export interface CompiledStyle {
+    css: string;
+    scopeAttribute?: string;
+}
+/** Compile CSS at build time; styles never depend on client hydration. */
+export declare function compileStyle(css: string, filename: string, global?: boolean): CompiledStyle;

package/dist/src/styles.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import postcss from 'postcss';
+import selectorParser from 'postcss-selector-parser';
+function scopeSelector(selector, attribute) {
+    const scopeNode = selectorParser().astSync(`:where([${attribute}])`).first
+        ?.first;
+    if (!scopeNode)
+        throw new Error('Could not create a style scope.');
+    return selectorParser((selectors) => {
+        selectors.each((part) => {
+            if (part.toString().includes(':global(')) {
+                throw new Error('Use <style global> for global selectors.');
+            }
+            let compound = [];
+            const addScope = () => {
+                if (compound.length === 0)
+                    return;
+                const pseudoElement = compound.find((node) => node.type === 'pseudo' && node.value.startsWith('::'));
+                if (pseudoElement)
+                    part.insertBefore(pseudoElement, scopeNode.clone());
+                else
+                    part.insertAfter(compound.at(-1), scopeNode.clone());
+                compound = [];
+            };
+            for (const node of [...part.nodes]) {
+                if (node.type === 'combinator')
+                    addScope();
+                else
+                    compound.push(node);
+            }
+            addScope();
+        });
+    }).processSync(selector);
+}
+/** Compile CSS at build time; styles never depend on client hydration. */
+export function compileStyle(css, filename, global = false) {
+    const root = postcss.parse(css, { from: filename });
+    root.walkAtRules((rule) => {
+        if (rule.name === 'import' || rule.name === 'charset') {
+            throw new Error(`${filename}: @${rule.name} belongs in a global stylesheet.`);
+        }
+        if (/keyframes$/i.test(rule.name) && !global) {
+            throw new Error(`${filename}: put @keyframes in <style global>.`);
+        }
+    });
+    if (global)
+        return { css: root.toString().trim() };
+    const scopeAttribute = `data-workstar-${createHash('sha256')
+        .update(filename)
+        .digest('hex')
+        .slice(0, 10)}`;
+    root.walkRules((rule) => {
+        rule.selector = scopeSelector(rule.selector, scopeAttribute);
+    });
+    return { css: root.toString().trim(), scopeAttribute };
+}

package/dist/src/vite.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+export interface WorkstarPluginOptions {
+    source?: string;
+}
+/** Compile authored components as Vite modules without writing into src. */
+export declare function workstar(options?: WorkstarPluginOptions): Plugin;

package/dist/src/vite.js

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import ts from 'typescript';
+import { compileComponentParts } from './index.js';
+/** Compile authored components as Vite modules without writing into src. */
+export function workstar(options = {}) {
+    let sourceDirectory;
+    const styleSuffix = '.css?workstar-style';
+    function isAuthoredComponent(filename) {
+        const localPath = relative(sourceDirectory, filename);
+        return (extname(localPath) === '.workstar' &&
+            localPath !== '..' &&
+            !localPath.startsWith(`..${sep}`) &&
+            !isAbsolute(localPath));
+    }
+    return {
+        name: 'workstar',
+        enforce: 'pre',
+        configResolved(config) {
+            sourceDirectory = resolve(config.root, options.source ?? 'src');
+        },
+        resolveId(id) {
+            if (!id.endsWith(styleSuffix))
+                return null;
+            const filename = id.slice(0, -styleSuffix.length);
+            return isAuthoredComponent(filename) ? id : null;
+        },
+        async load(id) {
+            if (!id.endsWith(styleSuffix))
+                return null;
+            const filename = id.slice(0, -styleSuffix.length);
+            if (!isAuthoredComponent(filename))
+                return null;
+            const source = await readFile(filename, 'utf8');
+            return compileComponentParts(source, filename).css;
+        },
+        transform(source, id) {
+            const filename = id.split('?', 1)[0];
+            if (!isAuthoredComponent(filename))
+                return null;
+            const generated = compileComponentParts(source, filename, {
+                componentImports: 'source',
+                cssImport: `${filename}${styleSuffix}`,
+            });
+            return {
+                code: ts.transpileModule(generated.code, {
+                    fileName: filename,
+                    compilerOptions: {
+                        module: ts.ModuleKind.ESNext,
+                        target: ts.ScriptTarget.ES2022,
+                    },
+                }).outputText,
+                map: null,
+            };
+        },
+        handleHotUpdate(context) {
+            if (!isAuthoredComponent(context.file))
+                return;
+            const stylesheet = context.server.moduleGraph.getModuleById(`${context.file}${styleSuffix}`);
+            if (!stylesheet)
+                return;
+            context.server.moduleGraph.invalidateModule(stylesheet);
+            return [...context.modules, stylesheet];
+        },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "workstar-compiler",
+  "version": "0.1.0",
+  "description": "Component compiler and Vite plugin for Workstar applications.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Workstar Lab <hello@workstarlab.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wslab-ai/workstar.git",
+    "directory": "packages/compiler"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./vite": {
+      "types": "./dist/src/vite.d.ts",
+      "import": "./dist/src/vite.js"
+    }
+  },
+  "bin": {
+    "workstar-compile": "./bin/workstar-compile.mjs"
+  },
+  "scripts": {
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run tests",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "parse5": "^8.0.0",
+    "postcss": "^8.5.28",
+    "postcss-selector-parser": "^7.1.6",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}