@heshammesalam/heshjs 0.2.0 → 0.5.0

package/dist/vite/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,MAAM,UAAU,IAAI;IAClB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO;QACL,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;QAC9B,MAAM,KAAK,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACvC,cAAc,CAAC,MAAM,IAAI,UAAU,GAAG,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC;QACnE,SAAS,CAAC,MAAM,EAAE,EAAE;YAClB,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,OAAO;YAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC;YAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QAC1C,CAAC;QACD,eAAe,CAAC,OAAO;YACrB,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAAC,OAAO,EAAE,CAAC;YAAC,CAAC;QACrG,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { Plugin } from 'vite';\nimport { compile } from '../compiler/index.js';\nexport function hesh(): Plugin {\n  let production = false;\n  return {\n    name: 'heshjs', enforce: 'pre',\n    config() { return { appType: 'spa' }; },\n    configResolved(config) { production = config.command === 'build'; },\n    transform(source, id) {\n      if (!id.endsWith('.hesh')) return;\n      const result = compile(source, { filename: id, development: !production });\n      return { code: result.code, map: null };\n    },\n    handleHotUpdate(context) {\n      if (context.file.endsWith('.hesh')) { context.server.ws.send({ type: 'full-reload' }); return []; }\n    }\n  };\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Plugin } from 'vite';\nimport { compile } from '../compiler/index.js';\nimport { createArchitectureCompiler, writeProject, formatDiagnostic, type ProjectOptions } from '../architecture/index.js';\nimport { resolve } from 'node:path';\nexport function hesh(options: { architecture?: ProjectOptions } = {}): Plugin {\n  let production = false;\n  const architecture = createArchitectureCompiler();\n  let project: ProjectOptions | undefined;\n  let watched: string[] = [];\n  let warn: ((message: string) => void) | undefined;\n  const check = () => {\n    if (!project) return;\n    const result = architecture.check(project);\n    if (result.diagnostics.some(item => item.severity === 'error')) throw new Error(result.diagnostics.map(formatDiagnostic).join('\\n'));\n    for (const item of result.diagnostics) if (item.severity === 'warning') warn?.(formatDiagnostic(item));\n    writeProject(result); watched = result.files;\n  };\n  return {\n    name: 'heshjs', enforce: 'pre',\n    config() { return { appType: 'spa' }; },\n    configResolved(config) {\n      production = config.command === 'build';\n      warn = message => config.logger.warn(message);\n      if (options.architecture) { project = { ...options.architecture, root: resolve(config.root, options.architecture.root) }; check(); }\n    },\n    buildStart() { for (const file of watched) this.addWatchFile(file); },\n    transform(source, id) {\n      if (project && /(?:^|\\/)server(?:\\/|$)|\\.server\\.[cm]?[jt]s$/.test(id.replace(/\\\\/g, '/'))) throw new Error(`HESH-SEC-001 Server-only module cannot enter the browser bundle: ${id}`);\n      if (!id.endsWith('.hesh')) return;\n      const result = compile(source, { filename: id, development: !production });\n      return { code: result.code, map: null };\n    },\n    handleHotUpdate(context) {\n      if (project && (watched.includes(context.file.replace(/\\\\/g, '/').toLowerCase()) || watched.includes(context.file.replace(/\\\\/g, '/')))) {\n        check(); context.server.ws.send({ type: 'full-reload' }); return [];\n      }\n      if (context.file.endsWith('.hesh')) { context.server.ws.send({ type: 'full-reload' }); return []; }\n    }\n  };\n}\n"]}

package/docs/contracts.md

@@ -0,0 +1,67 @@
+# Architecture declaration grammar (experimental)
+
+These declarations extend the existing Hesh lexer/parser. A file may contain
+views or architecture declarations; project compilation resolves architecture.
+Imports in architecture files reference other .hesh descriptor files explicitly.
+
+```ebnf
+domain = "domain", Identifier, "{",
+  "implementation", ":", String, ";",
+  [ "owns", "{", { Identifier, ";" }, "}" ],
+  "exposes", "{", { Path, ";" }, "}",
+  [ "consumes", "{", { Path, ";" }, "}" ],
+  [ "access", "{", { Path, ":", String, ";" }, "}" ], "}" ;
+presentation = "presentation", Identifier, "{",
+  "html", ":", String, ";", "logic", ":", String, ";",
+  [ "styles", ":", String, ";" ],
+  "bindings", "{", { Identifier, ";" }, "}",
+  "actions", "{", { Identifier, ";" }, "}",
+  [ "parts", "{", { Identifier, ";" }, "}" ], "}" ;
+destination = "destination", Identifier, "{",
+  "url", ":", String, ";",
+  "input", "{", { Identifier, ":", ("string" | "number" | "boolean"), ";" }, "}",
+  "presentation", ":", Identifier, ";", [ "access", ":", String, ";" ], "}" ;
+application = "application", Identifier, "{",
+  "domains", "{", { Identifier, ";" }, "}",
+  "destinations", "{", { Identifier, ";" }, "}", "}" ;
+Path = Identifier, { ".", Identifier } ;
+```
+
+Fields/blocks can appear in any order, once each. Unknown/duplicate fields are
+errors. Strings use ordinary JS string escaping. Identifiers cannot be prototype
+mutation names. Locations are retained for diagnostics. Semicolons are required.
+
+`implementation` and `logic` have form `./module.js#exportName` (or .ts/.mjs).
+A domain factory takes a dependencies object and returns its actual API. Every
+exposed dotted operation must exist and be callable according to the TS checker;
+every consumed path is Domain.operation and must be publicly exposed. An access
+entry must name an exposed operation. `owns` is ownership metadata, not a generated
+entity/validation/database implementation. The runtime passes only declared
+consumed operations and exposes only the validated public facade.
+
+A presentation factory receives `{ domains, input, location, signal }` and returns
+`{ bindings, actions }`. bindings values may be signals/readers/ordinary values;
+actions are callable. Both declared names and nested template paths are checked
+against its inferred JS/TS return shape. HTML text `{product.name}` is escaped via
+text nodes. `h-bind="product.name"` binds textContent (cannot have child content),
+`h-action="reserve"` listens to click (submit on a form), `h-value="quantity"`
+binds a writable signal to an input/textarea/select, and
+`h-destination="ProductDetails" h-input-id="product.id"` binds a native anchor to
+a validated destination. Other normal HTML attributes/semantics are preserved.
+No arbitrary JS expressions, raw HTML, inline event attributes, script elements,
+h-each, h-key or unknown h-* directives are accepted in this first milestone.
+Use normal CSS files; template scoping and keyed template lists remain deferred.
+
+Standalone presentations also compile to reusable HTML screens. `h-outlet` on an
+empty container creates the persistent shell's destination outlet (not permitted
+inside destination screens). `h-part="Badge"` mounts a declared nested Hesh Unit
+from the factory's `parts.Badge`. Parts inherit the parent context and disposal
+scope. A container may have only one of h-bind, h-outlet or h-part and no children.
+
+Destination URL params must exactly match input names. Values are encoded/decoded
+once; number inputs must be finite and booleans serialize as true/false. Duplicate
+or structurally conflicting URL destinations are errors. Generated declarations
+provide TS input types and JS IntelliSense. Runtime validation also rejects missing,
+extra or invalid fields in JavaScript. Destination policy names are client metadata;
+they cannot enforce server-side authorization. A policy without an authorize
+callback is denied rather than silently accepted.

package/docs/domain-graph.md

@@ -0,0 +1,205 @@
+# Domain Graph first vertical slice (0.3)
+
+This opt-in architecture builds on the existing Hesh compiler, shallow reactivity,
+DOM renderer, router and HMVC. Existing components and `createRouter` remain valid.
+This is the first architecture milestone, not an enterprise-ready framework.
+These APIs require 0.3 or later. Install `@heshammesalam/heshjs@0.3.0` in an
+existing Vite application and enable the architecture option described below.
+The npm creator's default template remains HMVC; it does not scaffold domains.
+The following commands run the reference examples from the framework repository:
+
+```sh
+npm install
+npm run check:architecture
+npm run dev:domains       # JS Identity/Inventory/Finance demo, localhost:5180
+npm run dev:domains:ts    # strict TS alternative, localhost:5181
+```
+
+The JS demo uses mock identity, an abortable timer-backed mock product API and a
+mock tax service. No HTTP server, credentials, payments or real authorization are
+implemented. Browser refresh restores destination/path input, not in-memory demo
+login state. Journeys are deliberately not simulated.
+
+## Descriptors and real implementations
+
+```hesh
+domain Inventory {
+  implementation: "./inventory.js#createInventory";
+  owns { Product; }
+  exposes { products.get; stock.reserve; }
+  consumes { Identity.session; }
+  access { stock.reserve: "inventory.reserve"; }
+}
+presentation ProductScreen {
+  html: "./ui/product.html";
+  logic: "./ui/product.js#createProduct";
+  styles: "./ui/product.css";
+  bindings { title; }
+  actions { reserve; }
+}
+destination ProductDetails {
+  url: "/products/:id";
+  input { id: string; }
+  presentation: ProductScreen;
+  access: "inventory.read";
+}
+```
+
+```js
+// inventory.js: private implementation, no imports from another domain's files.
+export function createInventory(dependencies) {
+  return {
+    products: { get: id => ({ id, title: 'Mock product' }) },
+    stock: { reserve: id => dependencies.Identity.session() + ': ' + id }
+  };
+}
+```
+
+`owns` is metadata, not a generated entity/database/validation system. Exposes are
+checked against the real factory return type. Consumers receive only the listed
+public operations, not the whole implementation object. Factories execute once
+per application domain graph in dependency order. Cycles and missing contracts
+are errors. Dependencies and public facades are frozen; disposed graphs reject
+further operation calls. Factories may use `onCleanup` for owned resources.
+
+The application descriptor imports domain files explicitly and selects names:
+
+```hesh
+import "./domains/identity/domain.hesh";
+import "./domains/inventory/domain.hesh";
+application Shop {
+  domains { Identity; Inventory; }
+  destinations { ProductDetails; }
+}
+```
+
+Every selected destination/presentation belongs to one selected domain directory.
+Each domain has its own directory boundary. Shared code can be imported by domains;
+shared code cannot re-export a private domain implementation as an escape hatch.
+
+## Standard HTML, CSS and explicit bindings
+
+```html
+<section aria-labelledby="title">
+  <h1 id="title">{title}</h1>
+  <button h-action="reserve">Reserve</button>
+</section>
+```
+
+```js
+import { signal } from '@heshammesalam/heshjs';
+export function createProduct({ domains, input, location, signal: cancellation }) {
+  const title = signal(domains.Inventory.products.get(input.id).title);
+  return {
+    bindings: { title },
+    actions: { reserve() { domains.Inventory.stock.reserve(input.id); } }
+  };
+}
+```
+
+Bindings are explicit declared data paths, not arbitrary evaluated JS strings.
+`{product.name}` and `h-bind="product.name"` use text nodes. `\{`/`\}` produce
+literal braces. A whole attribute binding like `disabled="{disabled}"` preserves
+boolean values; mixed attribute text is a string. Standard native HTML/custom tags
+are preserved without Hesh element aliases. Browser forms, labels, ARIA and native
+validation remain available. `h-action` means click, or submit on a form (preventing
+full submission). Events are passed to actions and async errors use onError.
+`h-value="email"` is two-way binding to a root writable signal on text controls.
+
+`h-destination="ProductDetails" h-input-id="productId"` on a native anchor builds
+a real href from the destination contract. Input attributes follow HTML's case
+insensitivity; destination input names must therefore be unique ignoring case.
+Missing/extra/wrongly typed inputs, missing bindings/actions and unsafe directives
+produce located diagnostics. Dynamic any-typed data emits warnings when the shape
+cannot be proven. JS receives inferred checks/JSDoc where present and runtime
+input validation; this does not make arbitrary JavaScript fully type-safe.
+
+HTML is parsed with parse5 at build time and emitted as DOM instructions. No
+innerHTML/eval/Function constructor is used. Script/embedding/foreign/template
+elements, inline event attributes and unknown h-* directives are rejected. SVG,
+keyed h-each, raw HTML and scoped CSS are not implemented in this slice. Standard
+CSS is imported unchanged through Vite, including variables, modern selectors,
+media/container queries, animations and global themes. CSS is global in this release.
+
+## Generated typed destinations
+
+Configure Vite using `hesh({ architecture: { root: 'src' } })`. For a tsconfig
+outside src add `tsconfig: '../tsconfig.json'`. The plugin validates before build
+and generates `src/.hesh-generated/app.js`, app.d.ts and compiled presentation
+modules. Do not hand-edit generated files. Invalid checks block build; last valid
+files are not deleted, so bypassing the check pipeline can use stale output.
+
+```js
+import { createApplication } from './.hesh-generated/app.js';
+const app = createApplication({
+  authorize: policy => policy === 'inventory.read', // CLIENT ONLY
+  onError: error => console.error(error),
+  onDiagnostic: event => console.debug(event.type, event.destination, event.reason)
+});
+const dispose = app.start(document.querySelector('#app'));
+app.destinations.ProductDetails.open({ id: '15' });
+app.destinations.ProductDetails.replace({ id: '20' }, { query: { tab: 'stock' } });
+await app.destinations.ProductDetails.prefetch({ id: '30' });
+```
+
+Generated declarations give each destination its exact required input fields and
+primitive types. Empty-input destinations use `Record<string, never>`. Runtime
+validation also rejects unknown/missing fields, non-finite numbers, empty strings
+and URL dot segments. Inputs are encoded once and decoded once; URL parameter
+names currently use the existing router's ASCII letter/digit/underscore rules.
+Overlapping destination patterns are rejected so an input cannot silently open a
+different static destination. This restriction applies only to the new contracts;
+the existing router retains its static-priority behavior.
+
+Page is the only supported presentation mode. Destinations load their own compiled
+presentation and logic resources lazily. Prefetch deduplicates those code loads;
+it does not fetch business data or authorize operations. Navigation disposes the
+previous presentation, aborts its signal and prevents a late loader from mounting
+stale UI. Dynamic module downloads themselves cannot be canceled. Factories are
+synchronous and start their own asynchronous work using the supplied signal.
+Guard against late results when using non-abortable services. Query/hash changes
+create a fresh presentation instance. Successful mounting focuses a heading or
+`data-hesh-focus`; scroll restoration and modal focus trapping are deferred.
+
+`app.status.get()` is reactive loading/ready/error state. Optional diagnostic
+events identify loading, ready, blocked, errors, cancellation and disposal. They
+do not infer business intent or explain arbitrary reactive dependency chains.
+Client policies default to deny when declared without an authorize callback;
+server-side enforcement is still necessary for every protected operation.
+
+## Architecture validation and graph tooling
+
+```sh
+hesh check ./src --write
+hesh check ./src --tsconfig ../tsconfig.json --write
+hesh graph ./src
+```
+
+From the repository use `node packages/heshjs/cli.js ...`. Root means the directory
+containing app.hesh, typically src. The TS resolver handles aliases, relative paths,
+type imports and re-exports. Canonical paths account for filesystem aliases and
+symlinks. Physical cross-domain imports of implementations are private, even if
+the target JS module exports a function; use declared injection instead. Node and
+server-only modules are blocked in client code. Computed imports in application
+source are rejected because their target cannot be validated. This is build-time
+architecture enforcement for configured projects, not a sandbox against malicious
+application code, reflection or uninspected third-party packages.
+
+Diagnostics include code, severity, path, offset/line/column, explanation and a
+suggestion. HTML locations identify their source node/attribute; entity decoding
+can make the exact inner text offset approximate. Graph JSON contains domain
+dependencies, destination ownership/input schemas and compiled navigation links.
+Descriptor ASTs are reused when unchanged and output writes are content-based.
+Semantic analysis currently rechecks the whole graph; precise dependency-aware
+typecheck invalidation and full HTML/Hesh source maps are deferred. The Vite workflow
+uses full reload rather than state-preserving HMR.
+
+## Deliberate limits
+
+Journeys, modal/panel/nested destination modes, redirects, scroll restoration,
+file routing, generic async resources/caching, deep collections, scoped CSS,
+server authorization, SSR/hydration, advanced scaffolding commands and a language
+server are not implemented. Existing HMVC nested routes remain usable separately.
+Production hosts still need SPA fallback to index.html for direct URLs. No
+performance superiority, globally unique architecture or enterprise-readiness
+claim is made. See architecture/domain-graph-audit.md for migration order.

package/docs/grammar.md

@@ -1,5 +1,9 @@
 # Milestone 1 language (v0.1)
 
+This remains the legacy component grammar. The opt-in architecture descriptor
+extension is specified separately in [contracts.md](contracts.md); it does not
+replace existing .hesh views or add template directives to the brace UI syntax.
+
 The grammar is deliberately smaller than the product roadmap. Source is UTF-8.
 Whitespace and JavaScript comments separate tokens. Identifiers follow JavaScript
 identifier rules. Strings and numbers follow JavaScript lexical rules.

package/docs/units.md

@@ -0,0 +1,71 @@
+# Unified HeshJS 0.5
+
+Use Node 22.12 or later:
+
+```sh
+npx @heshammesalam/heshjs@latest create
+```
+
+Choose your folder and JavaScript or TypeScript. JavaScript is the default.
+For automation: `npx @heshammesalam/heshjs@latest create my-site --ts`.
+Run `cd my-site`, `npm install`, then `npm run dev`.
+
+Only `@heshammesalam/heshjs` is needed for Hesh runtime/compiler/CLI features.
+Vite is the build tool; TypeScript is included in typed project development dependencies.
+The former `create-heshjs` package is a legacy entry point. Do not use `npm create`:
+that convention resolves a separate creator package. Use the unified npx command.
+
+```text
+src/
+  app.hesh
+  hesh-units/
+    identity/
+      unit.hesh
+      state.js              # .ts in typed projects
+      actions.js
+      parts/login/
+        state.js
+        actions.js
+        screen.html
+    workspace/
+      unit.hesh
+      state.js
+      actions.js
+      parts/home/...
+      parts/about/...
+      parts/counter/parts/detail/...
+  foundation/shell/
+    unit.hesh
+    unit.js
+    state.js
+    actions.js
+    screen.html
+    parts/badge/
+      unit.js
+      state.js
+      actions.js
+      screen.html
+```
+
+Hesh Units preserve hierarchical MVC ownership with Hesh-specific names. State
+corresponds to the model, actions to the controller, and screen to the view.
+`defineUnit` composes these using the same scope/parent/lifetime machinery as
+`defineModule`. `h-part="Badge"` mounts an explicitly declared child unit and
+disposes its state effects, DOM and listeners with its parent. Instances have
+independent state. `h-outlet` mounts the SPA destination outlet inside a persistent
+shell; it is not permitted inside asynchronous destination screens.
+
+Every starter UI screen is ordinary HTML, including shell and badge. `.hesh`
+files declare Domain Graph contracts; generated `.hesh-generated` JS and type
+declarations are compiler output. Existing brace views and `/hmvc` APIs remain
+available for compatibility. Domain Graph controls business dependencies and
+typed destinations; HTML units control hierarchy and ownership.
+
+Use `npm run check` for architecture checks (plus strict tsc in typed projects),
+`npm run graph` for dependencies, and `npm run build` for production. The supplied
+logo is bundled locally and used as favicon. The session is an in-memory demo;
+production authorization needs server enforcement. Configure the production host
+to serve index.html for app URLs while serving real static assets normally.
+
+Unsupported features remain unsupported: SSR, Journeys, deep reactivity and
+keyed HTML template lists. Native HTML bindings accept data paths, not arbitrary JS.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@heshammesalam/heshjs",
-  "version": "0.2.0",
-  "description": "An experimental independent reactive UI framework with brace-based .hesh components",
+  "version": "0.5.0",
+  "description": "Independent reactive UI framework with HTML screens, hierarchical Hesh Units, Domain Graph and an integrated project CLI",
   "author": "Hesham",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,11 +16,17 @@
     "./vite": { "types": "./dist/vite/index.d.ts", "import": "./dist/vite/index.js" },
     "./router": { "types": "./dist/router/index.d.ts", "import": "./dist/router/index.js" },
     "./hmvc": { "types": "./dist/hmvc/index.d.ts", "import": "./dist/hmvc/index.js" },
+    "./units": { "types": "./dist/units/index.d.ts", "import": "./dist/units/index.js" },
+    "./domains": { "types": "./dist/domains/index.d.ts", "import": "./dist/domains/index.js" },
+    "./destinations": { "types": "./dist/destinations/index.d.ts", "import": "./dist/destinations/index.js" },
+    "./presentation": { "types": "./dist/presentation/index.d.ts", "import": "./dist/presentation/index.js" },
+    "./architecture": { "types": "./dist/architecture/index.d.ts", "import": "./dist/architecture/index.js" },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "src", "docs", "README.md"],
+  "files": ["dist", "src", "docs", "README.md", "cli.js", "scaffold"],
+  "bin": { "hesh": "./cli.js" },
   "engines": { "node": ">=22.12.0" },
-  "dependencies": { "typescript": "~5.9.3" },
+  "dependencies": { "typescript": "~5.9.3", "parse5": "8.1.0" },
   "peerDependencies": { "vite": "^7.2.2" },
   "peerDependenciesMeta": { "vite": { "optional": true } },
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }

package/scaffold/create.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { mkdir, readdir, writeFile, readFile } from 'node:fs/promises';
+import { resolve, basename, join, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { stdin, stdout } from 'node:process';
+import { applicationFiles } from './template.js';
+
+export async function createProject(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: hesh create [directory] [--ts | --js]\nOmit directory/language to choose interactively.');
+    return;
+  }
+  const flags = args.filter(arg => arg.startsWith('--'));
+  if (flags.some(flag => !['--ts', '--js'].includes(flag)) || (flags.includes('--ts') && flags.includes('--js'))) throw new Error('Choose --ts or --js. Use --help for usage.');
+  const directories = args.filter(arg => !arg.startsWith('--'));
+  if (directories.length > 1) throw new Error('Provide at most one project directory. Use --help for usage.');
+  let terminal, lines, interrupted = false;
+  const ask = async (question, validate) => {
+    if (!terminal) {
+      terminal = createInterface({ input: stdin, output: stdout, terminal: Boolean(stdin.isTTY && stdout.isTTY) });
+      lines = terminal[Symbol.asyncIterator]();
+      terminal.on('SIGINT', () => { interrupted = true; terminal.close(); });
+    }
+    while (true) {
+      stdout.write(question);
+      const answer = await lines.next();
+      if (answer.done) {
+        const error = new Error(interrupted ? 'Project creation canceled.' : 'Input ended. Provide a directory and --js or --ts for non-interactive use.');
+        error.exitCode = interrupted ? 130 : 1;
+        throw error;
+      }
+      const value = validate(answer.value.trim());
+      if (value !== undefined) return value;
+    }
+  };
+  let directory, typed, target;
+  try {
+    console.log('\nHeshJS — Create your application\n');
+    directory = directories[0] ?? await ask('Project folder: ', answer => {
+      if (answer && !answer.includes('\0')) return answer;
+      console.log('Enter the folder name or path you want to create.');
+    });
+    target = resolve(directory);
+    let existing;
+    try { existing = await readdir(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (existing?.length) throw new Error(`Directory is not empty: ${target}`);
+    typed = flags.includes('--ts') ? true : flags.includes('--js') ? false : await ask('Choose language:\n  1. JavaScript\n  2. TypeScript\nLanguage [1]: ', answer => {
+      const choice = answer.toLowerCase();
+      if (['', '1', 'js', 'javascript'].includes(choice)) return false;
+      if (['2', 'ts', 'typescript'].includes(choice)) return true;
+      console.log('Enter 1 for JavaScript or 2 for TypeScript.');
+    });
+  } finally { terminal?.close(); }
+
+  // Read the bundled asset before creating any project files.
+  const icon = await readFile(new URL('./assets/hesh-icon.png', import.meta.url));
+  const name = basename(target).toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'hesh-app';
+  const files = {
+    'package.json': JSON.stringify({ name, private: true, version: '0.0.0', type: 'module', scripts: { dev: 'vite', check: 'hesh check src --write' + (typed ? ' && tsc --noEmit' : ''), graph: 'hesh graph src', build: 'hesh check src --write && ' + (typed ? 'tsc --noEmit && ' : '') + 'vite build', preview: 'vite preview' }, dependencies: { '@heshammesalam/heshjs': '0.5.0' }, devDependencies: { vite: '^7.2.2', ...(typed ? { typescript: '~5.9.3' } : {}) } }, null, 2) + '\n',
+    '.gitignore': 'node_modules/\ndist/\n',
+    'index.html': `<!doctype html>\n<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="icon" type="image/png" href="/brand/hesh-icon.png"><link rel="apple-touch-icon" href="/brand/hesh-icon.png"><title>HeshJS</title></head><body><div id="app"></div><script type="module" src="/src/main.${typed ? 'ts' : 'js'}"></script></body></html>\n`,
+    'vite.config.js': "import { hesh } from '@heshammesalam/heshjs/vite';\nexport default { plugins: [hesh({ architecture: { root: 'src'" + (typed ? ", tsconfig: '../tsconfig.json'" : '') + " } })] };\n",
+    'src/style.css': ':root { font: 17px/1.6 system-ui; background: #f3f6fb; color: #17243a; } #app { max-width: 900px; margin: 5vh auto; padding: 32px; background: white; border-radius: 16px; } .hesh-brand { display: flex; align-items: center; gap: 16px; margin-bottom: 24px; } .hesh-brand img { display: block; width: 80px; height: 80px; object-fit: contain; flex: 0 0 80px; } .hesh-brand h1 { margin: 0; font-size: clamp(1.3rem, 4vw, 2rem); } nav { display: flex; flex-wrap: wrap; gap: 20px; } button,input { font: inherit; margin-right: 12px; padding: 8px 16px; } button { cursor: pointer; } button:focus-visible, a:focus-visible, input:focus-visible { outline: 3px solid #2563eb; } main { padding: 20px 0; } footer { border-top: 1px solid #dbe3ef; padding-top: 16px; } .architecture-note { padding: 12px; background: #f0f4ff; border-radius: 8px; } @media(max-width:600px) { #app { margin: 0; padding: 20px; border-radius: 0; } }\n',
+    'public/brand/hesh-icon.png': icon,
+    ...applicationFiles(typed)
+  };
+  if (typed) {
+    files['tsconfig.json'] = JSON.stringify({ compilerOptions: { target: 'ES2022', module: 'ESNext', moduleResolution: 'Bundler', strict: true, noEmit: true, allowImportingTsExtensions: true, skipLibCheck: true, types: ['vite/client'] }, include: ['src'] }, null, 2) + '\n';
+    files['src/hesh.d.ts'] = "declare module '*.hesh' {\n  import type { Component } from '@heshammesalam/heshjs';\n  const component: Component;\n  export default component;\n}\n";
+  }
+  await mkdir(target, { recursive: true });
+  for (const [path, content] of Object.entries(files)) {
+    await mkdir(dirname(join(target, path)), { recursive: true });
+    await writeFile(join(target, path), content, { flag: 'wx' });
+  }
+  console.log(`Created ${typed ? 'TypeScript' : 'JavaScript'} HeshJS project in ${target}\n\nNext:\n  cd ${JSON.stringify(directory)}\n  npm install\n  npm run dev`);
+}
+