@bytefaceinc/web-lang 0.1.1

package/LICENSE

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

@@ -0,0 +1,277 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/theRegex/web-lang/main/assets/logo-w.png" alt="WEB Lang logo" width="180" />
+</p>
+
+<h1 align="center">WEB Lang</h1>
+
+<p align="center">
+  <strong>.web is a power doc for rich website layouts.</strong>
+</p>
+
+<p align="center">
+  Write structure, styling, metadata, responsive behavior, and small compile-time helpers in one language, then initialize starter projects, compile to standard HTML and CSS, render polished screenshots, or keep a live watch session running while you iterate.
+</p>
+
+<img src="https://raw.githubusercontent.com/theRegex/web-lang/main/assets/banner-illustrated.png" alt="WEB Lang banner"/>
+
+## What WEB Lang Is
+
+WEB Lang is a compiler and CLI for `.web` files.
+
+A `.web` file is designed to feel like a power doc:
+
+- one source file for the page
+- one mental model for structure and styling
+- one place to express semantic layout, attributes, metadata, states, and responsive rules
+- normal web-native output at the end
+
+That means you author in one language, but ship plain HTML and CSS.
+
+## Philosophy
+
+WEB Lang is built around a simple idea:
+
+> Rich website layouts should be easy to author without splitting design thinking across too many files too early.
+
+The philosophy behind `.web` is:
+
+- design and implementation should stay close together
+- semantic structure should be easy to read at a glance
+- shared styles should be reusable without a framework requirement
+- HTML attributes and document metadata should stay explicit
+- the final output should still be portable, reviewable, and standards-based
+
+In practice, `.web` gives designers and developers a common source of truth for a page.
+
+## Highlights
+
+- Initialize a new WEB project with `web init`.
+- Author `.web` source and compile to HTML and CSS.
+- Render a compiled page to JPG or PNG with `web screenshot`.
+- Keep a live watch session running with `web watch`.
+- Use semantic type declarations such as `Main`, `Section`, `Heading1`, and `Link`.
+- Define reusable tokens and shared style families in one top-level `define { ... }` block.
+- Add real HTML attributes with `::attrs`.
+- Add head metadata with `::head`.
+- Emit browser scripts with `::script`.
+- Add states with pseudo blocks like `::hover`.
+- Add responsive behavior with `::media`.
+- Use compile-time `js` literals for small generated values.
+- Keep an escape hatch with `raw` for targeted CSS that does not fit the core language.
+- Run the package as a CLI with `web`.
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g @bytefaceinc/web-lang
+```
+
+Then run:
+
+```bash
+web init
+```
+
+Or scaffold into a named directory:
+
+```bash
+web init website
+```
+
+Or compile an existing file:
+
+```bash
+web home.web
+```
+
+Or render a screenshot:
+
+```bash
+web screenshot home.web
+```
+
+Or watch for changes:
+
+```bash
+web watch home.web
+```
+
+For local development in a checkout:
+
+```bash
+npm link
+web init
+```
+
+```bash
+npm link
+web home.web
+```
+
+WEB Lang supports Node.js `18+`.
+
+## Quick Start
+
+Initialize a starter project in a clean directory:
+
+```bash
+web init
+```
+
+Initialize the current directory explicitly:
+
+```bash
+web init .
+```
+
+Initialize a new `website` folder and create it if it does not exist yet:
+
+```bash
+web init website
+```
+
+That creates:
+
+- `index.web`
+- `index.html`
+- `index.css`
+- `web-lang-agents.md`
+
+The generated `web-lang-agents.md` combines the packaged getting-started guide, CLI guide, and compiler reference into one local file so coding agents can load the current WEB context quickly.
+
+Compile one `.web` file:
+
+```bash
+web home.web
+```
+
+Compile the same file without writing the extension:
+
+```bash
+web home
+```
+
+Compile every `.web` file in the current directory:
+
+```bash
+web .
+```
+
+Compile matching files from another directory:
+
+```bash
+web ./code/*
+```
+
+Render a full-page screenshot at the default width:
+
+```bash
+web screenshot home.web
+```
+
+Render a viewport-sized JPG with an explicit device scale factor:
+
+```bash
+web screenshot home.web --jpg 1080 1080 2
+```
+
+Keep a file compiling automatically while you work:
+
+```bash
+web watch home.web
+```
+
+Keep a watch session running and capture a baseline screenshot plus timed snapshots every 5 minutes:
+
+```bash
+web watch home.web -s
+```
+
+Each source file compiles to matching output files next to the source:
+
+- `home.web` -> `home.html`
+- `home.web` -> `home.css`
+
+Screenshots are written into a screenshot workspace rooted at the current working directory:
+
+- `web screenshot home.web` -> `web-lang-screenshots/home-YYYY-MM-DD_HH-mm-ss-SSS.jpg`
+- `web screenshot pages/about.web` -> `web-lang-screenshots/pages/about-YYYY-MM-DD_HH-mm-ss-SSS.jpg`
+
+The CLI creates `./web-lang-screenshots` automatically the first time it needs it, and appends a human-readable local timestamp to each screenshot filename so repeated captures do not overwrite each other.
+
+When `web watch <source> -s` is enabled, the watch session uses the same screenshot workspace and filename format. Watch sessions stop automatically after 1 hour of no recent source activity and print a verbose exit summary explaining why the process closed.
+
+When `web init` runs, it writes `web-lang-agents.md` into the chosen project root. That file bundles `docs/getting-started.md`, `docs/cli.md`, and `docs/compiler.md` in that order so local agents have one up-to-date context document to read. If you pass a directory like `website`, WEB creates that directory first when needed.
+
+## Programmatic API
+
+WEB Lang can also be used as a Node module:
+
+```js
+const { compileFile, compileSource, resolveCompileOutputPaths } = require('@bytefaceinc/web-lang');
+
+const result = compileFile('./home.web');
+
+console.log(result.htmlPath);
+console.log(result.cssPath);
+console.log(result.stats);
+```
+
+The package exports:
+
+- `compileFile(inputPath, options)`
+- `compileSource(source, options)`
+- `resolveCompileOutputPaths(inputPath, options)`
+- `CompilerError`
+
+## Documentation
+
+Start here:
+
+- [Getting Started](./docs/getting-started.md)
+- [Language Guide](./docs/language-guide.md)
+- [CLI Guide](./docs/cli.md)
+- [Compiler Reference](./docs/compiler.md)
+- [Error Handling](./docs/error-handling.md)
+
+## Agent Support
+
+This repo includes committed agent-facing context for the major repository instruction surfaces used by current coding agents:
+
+- [AGENTS.md](./AGENTS.md) for repo-wide instructions, with scoped overrides in `docs/`, `lib/cli/`, and `syntax_highlighter/`
+- [CLAUDE.md](./CLAUDE.md) plus `.claude/rules/` for Claude Code
+- `.github/copilot-instructions.md`, `.github/instructions/`, and `.github/agents/` for GitHub Copilot
+- [web-lang-agents.md](./web-lang-agents.md) and [docs/agents/README.md](./docs/agents/README.md) for deeper WEB Lang maintainer context
+
+Generated projects created by `web init` still receive their own local `web-lang-agents.md` context file bundled from the packaged getting-started, CLI, and compiler docs.
+
+## Why It Feels Different
+
+Many tools ask you to split a page into separate structure, style, metadata, and behavior files very early.
+
+WEB Lang intentionally starts from a different place:
+
+- a page is a document
+- a document can still be expressive
+- structure and styling are easier to reason about when they live close together
+
+That is why `.web` is a power doc: it is not only a template format and not only a styling language. It is a single authoring surface for rich website layouts.
+
+## Publishing Notes
+
+This package is structured for public distribution with:
+
+- a public-ready `package.json`
+- a CLI binary entry in `bin`
+- a documented Node API export
+- a curated `files` list for clean package contents
+- a license file
+- package-local docs and branding assets
+
+To preview the published package contents:
+
+```bash
+npm pack --dry-run
+```

package/bin/web.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../lib/cli');
+const { printUnexpectedCliError } = require('../lib/cli/shared');
+
+main().catch((error) => {
+  printUnexpectedCliError(error);
+  process.exit(1);
+});