@heshammesalam/heshjs 0.3.0 → 0.5.0

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`);
+}
+

package/scaffold/template.js

@@ -0,0 +1,188 @@
+export function applicationFiles(typed) {
+  const ext = typed ? 'ts' : 'js';
+  const runtime = '@heshammesalam/heshjs';
+  const files = {
+    'src/app.hesh': `import "./hesh-units/identity/unit.hesh";
+import "./hesh-units/workspace/unit.hesh";
+application App {
+  domains { Identity; Workspace; }
+  destinations { Home; About; CounterDetails; Login; }
+}
+`,
+    [`src/main.${ext}`]: `import { createApplication } from './.hesh-generated/app.js';
+import { createShellUnit } from './foundation/shell/unit.${ext}';
+import './style.css';
+const root = document.querySelector('#app');
+if (!root) throw new Error('Missing #app');
+const application = createApplication();
+let dispose = () => application.stop();
+try {
+  const url = new URL(window.location.href);
+  const shell = createShellUnit(application).attach(root, {
+    url, pathname: url.pathname, params: {}, query: url.searchParams, hash: url.hash
+  });
+  dispose = () => { try { application.stop(); } finally { shell.dispose(); } };
+  if (!shell.outlet) throw new Error('Shell must render h-outlet');
+  application.start(shell.outlet);
+} catch (error) {
+  dispose();
+  throw error;
+}
+if (import.meta.hot) import.meta.hot.dispose(dispose);
+`,
+    'src/hesh-units/identity/unit.hesh': `domain Identity {
+  implementation: "./actions.${ext}#createDomain";
+  owns { Session; }
+  exposes { session.current; session.login; }
+}
+presentation LoginScreen {
+  html: "./parts/login/screen.html";
+  logic: "./parts/login/actions.${ext}#createLogin";
+  bindings { name; status; }
+  actions { signIn; }
+}
+destination Login { url: "/login"; input {} presentation: LoginScreen; }
+`,
+    [`src/hesh-units/identity/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ user: signal('Guest') });
+`,
+    [`src/hesh-units/identity/actions.${ext}`]: `import { createState } from './state.${ext}';
+export function createDomain() {
+  const state = createState();
+  ${typed ? '' : '/** @param {string} name */\n  '}const login = (name${typed ? ': string' : ''}) => state.user.set(name);
+  return { session: { current: () => state.user.get(), login } };
+}
+`,
+    [`src/hesh-units/identity/parts/login/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ name: signal('Hesham'), status: signal('Browser-memory demo session') });
+`,
+    [`src/hesh-units/identity/parts/login/actions.${ext}`]: `import { createState } from './state.${ext}';
+${typed ? "import type { createDomain } from '../../actions.ts';\n" : "/** @param {{ domains: { Identity: ReturnType<typeof import('../../actions.js').createDomain> } }} context */\n"}export function createLogin(context${typed ? ': { domains: { Identity: ReturnType<typeof createDomain> } }' : ''}) {
+  const state = createState();
+  return { bindings: state, actions: { signIn() {
+    context.domains.Identity.session.login(state.name.get());
+    state.status.set('Demo session updated. Navigate Home to see the injected domain contract.');
+  } } };
+}
+`,
+    'src/hesh-units/identity/parts/login/screen.html': `<section><h2>Identity domain</h2><p>This is an in-memory demo, not real authentication. Protected operations require server authorization.</p><form h-action="signIn"><label for="name">Display name</label><input id="name" required h-value="name"><button type="submit">Update demo session</button></form><p role="status" h-bind="status"></p><a h-destination="Home">Back Home</a></section>\n`,
+    'src/hesh-units/workspace/unit.hesh': `domain Workspace {
+  implementation: "./actions.${ext}#createDomain";
+  owns { Counter; }
+  exposes { counter.current; counter.increment; counter.decrement; viewer; }
+  consumes { Identity.session.current; }
+}
+presentation HomeScreen {
+  html: "./parts/home/screen.html";
+  logic: "./parts/home/actions.${ext}#createHome";
+  bindings { welcome; count; hint; id; }
+  actions { increment; decrement; }
+}
+presentation AboutScreen {
+  html: "./parts/about/screen.html";
+  logic: "./parts/about/actions.${ext}#createAbout";
+  bindings { description; }
+  actions {}
+}
+presentation DetailScreen {
+  html: "./parts/counter/parts/detail/screen.html";
+  logic: "./parts/counter/parts/detail/actions.${ext}#createDetail";
+  bindings { id; source; count; }
+  actions {}
+}
+destination Home { url: "/"; input {} presentation: HomeScreen; }
+destination About { url: "/about"; input {} presentation: AboutScreen; }
+destination CounterDetails { url: "/counter/:id"; input { id: string; } presentation: DetailScreen; }
+`,
+    [`src/hesh-units/workspace/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ count: signal(0) });
+`,
+    [`src/hesh-units/workspace/actions.${ext}`]: `import { createState } from './state.${ext}';
+${typed ? '' : '/** @param {{ Identity: { session: { current(): string } } }} dependencies */\n'}export function createDomain(dependencies${typed ? ': { Identity: { session: { current(): string } } }' : ''}) {
+  const state = createState();
+  return {
+    counter: { current: () => state.count.get(), increment: () => state.count.set(state.count.get() + 1), decrement: () => state.count.set(state.count.get() - 1) },
+    viewer: () => dependencies.Identity.session.current()
+  };
+}
+`,
+    [`src/hesh-units/workspace/parts/home/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ hint: signal('Domain state survives destination changes; presentation state has its own lifetime.') });
+`,
+    [`src/hesh-units/workspace/parts/home/actions.${ext}`]: `import { createState } from './state.${ext}';
+${typed ? "import type { createDomain } from '../../actions.ts';\n" : "/** @param {{ domains: { Workspace: ReturnType<typeof import('../../actions.js').createDomain> } }} context */\n"}export function createHome(context${typed ? ': { domains: { Workspace: ReturnType<typeof createDomain> } }' : ''}) {
+  const state = createState(), workspace = context.domains.Workspace;
+  return { bindings: { welcome: () => 'Welcome, ' + workspace.viewer(), count: () => workspace.counter.current(), hint: state.hint, id: '42' },
+    actions: { increment: () => workspace.counter.increment(), decrement: () => workspace.counter.decrement() } };
+}
+`,
+    'src/hesh-units/workspace/parts/home/screen.html': `<section><h2>Home · Workspace domain</h2><p h-bind="welcome"></p><p class="architecture-note">Domain Graph contracts + hierarchical Hesh Units: state / actions / screen / parts.</p><p>Domain counter: {count}</p><button h-action="increment">+</button><button h-action="decrement">-</button><p h-bind="hint"></p><a h-destination="CounterDetails" h-input-id="id">Open nested counter module</a></section>\n`,
+    [`src/hesh-units/workspace/parts/about/state.${ext}`]: `export const createState = () => ({ description: 'Domains own public contracts and dependencies. Each Hesh Unit keeps state, actions and an HTML screen together. The persistent shell and its badge use hierarchical ownership.' });
+`,
+    [`src/hesh-units/workspace/parts/about/actions.${ext}`]: `import { createState } from './state.${ext}';
+export const createAbout = () => ({ bindings: createState(), actions: {} });
+`,
+    'src/hesh-units/workspace/parts/about/screen.html': '<section><h2>Domain Graph + Hesh Units</h2><p h-bind="description"></p><a h-destination="Home">Home</a></section>\n',
+    [`src/hesh-units/workspace/parts/counter/parts/detail/state.${ext}`]: `import { signal } from '${runtime}';
+${typed ? '' : '/** @param {string} id */\n'}export const createState = (id${typed ? ': string' : ''}) => ({ id: signal(id) });
+`,
+    [`src/hesh-units/workspace/parts/counter/parts/detail/actions.${ext}`]: `import { createState } from './state.${ext}';
+${typed ? "import type { createDomain } from '../../../../actions.ts';\nimport type { RouteLocation } from '@heshammesalam/heshjs/router';\n" : "/** @param {{ input: { id: string }, location: import('@heshammesalam/heshjs/router').RouteLocation, domains: { Workspace: ReturnType<typeof import('../../../../actions.js').createDomain> } }} context */\n"}export function createDetail(context${typed ? ': { input: { id: string }; location: RouteLocation; domains: { Workspace: ReturnType<typeof createDomain> } }' : ''}) {
+  const state = createState(context.input.id);
+  return { bindings: { id: state.id, source: () => context.location.query.get('from') ?? 'direct link', count: () => context.domains.Workspace.counter.current() }, actions: {} };
+}
+`,
+    'src/hesh-units/workspace/parts/counter/parts/detail/screen.html': '<section><h2>Nested counter part</h2><p>Destination ID: {id}</p><p>Source: {source}</p><p>Shared domain counter: {count}</p><a h-destination="Home">Home</a></section>\n',
+    'public/_redirects': '/* /index.html 200\n',
+    'README.md': `# HeshJS Units\n\nOne package includes the runtime, compiler and CLI. Run npm install, npm run dev.\nUse npm run check, npm run graph and npm run build.\n\nHTML is the default: screen.html is the view, state.${ext} owns state, actions.${ext} owns behavior, unit.hesh declares contracts, and parts/ contains nested units.\nsrc/hesh-units contains business units; Domain Graph validates their public dependencies.\nsrc/foundation/shell is a persistent HTML unit with h-outlet and a nested h-part.\nShell and part state survives SPA navigation; page state is owned by the destination.\nThe bundled logo also serves as favicon. Identity is an in-memory demo session.\nProduction hosts must rewrite unknown app routes to index.html.\n`
+  };
+  files['src/app.hesh'] = 'import "./foundation/shell/unit.hesh";\n' + files['src/app.hesh'];
+  Object.assign(files, {
+    [`src/foundation/shell/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ clicks: signal(0) });
+`,
+    [`src/foundation/shell/actions.${ext}`]: `${typed ? "import type { createState } from './state.ts';\n" : ''}import { createBadgeUnit } from './parts/badge/unit.${ext}';
+${typed ? '' : '/** @param {ReturnType<typeof import(\'./state.js\').createState>} state\n * @param {{ domains: { Identity: { session: { current(): unknown } } }; destinations: object }} application */\n'}export function createActions(state${typed ? ': ReturnType<typeof createState>' : ''}, application${typed ? ': { domains: { Identity: { session: { current(): unknown } } }; destinations: object }' : ''}) {
+  return { bindings: { clicks: state.clicks, viewer: () => String(application.domains.Identity.session.current()), detailId: '42' },
+    actions: { increment: () => state.clicks.set(state.clicks.get() + 1) }, parts: { Badge: createBadgeUnit() } };
+}
+`,
+    [`src/foundation/shell/unit.${ext}`]: `import { defineUnit } from '${runtime}/units';
+import { createState } from './state.${ext}';
+import { createActions } from './actions.${ext}';
+import screen from '../../.hesh-generated/ShellScreen.js';
+${typed ? '' : '/** @param {{ domains: { Identity: { session: { current(): unknown } } }; destinations: object }} application */\n'}export function createShellUnit(application${typed ? ': { domains: { Identity: { session: { current(): unknown } } }; destinations: object }' : ''}) {
+  return defineUnit({ state: createState, actions: state => createActions(state, application), screen, destinations: application.destinations });
+}
+`,
+    'src/foundation/shell/screen.html': `<header><div class="hesh-brand"><img src="/brand/hesh-icon.png" alt="HeshJS logo" width="80" height="80"><h1>HeshJS · Graph + Units</h1></div><nav aria-label="Main navigation"><a h-destination="Home">Home</a><a h-destination="About">About</a><a h-destination="CounterDetails" h-input-id="detailId">Counter detail</a><a h-destination="Login">Demo identity</a><a href="/missing">Not found</a></nav><p>Demo user: {viewer}</p><p>Shell state: {clicks}</p><button h-action="increment">Keep shell state</button></header><main h-outlet></main><footer h-part="Badge"></footer>\n`,
+    'src/foundation/shell/unit.hesh': `presentation ShellScreen {
+  html: "./screen.html";
+  logic: "./actions.${ext}#createActions";
+  bindings { clicks; viewer; detailId; }
+  actions { increment; }
+  parts { Badge; }
+}
+presentation BadgeScreen {
+  html: "./parts/badge/screen.html";
+  logic: "./parts/badge/actions.${ext}#createActions";
+  bindings { count; }
+  actions { increment; }
+}
+`,
+    [`src/foundation/shell/parts/badge/state.${ext}`]: `import { signal } from '${runtime}';
+export const createState = () => ({ count: signal(0) });
+`,
+    [`src/foundation/shell/parts/badge/actions.${ext}`]: `${typed ? "import type { createState } from './state.ts';\n" : '/** @param {ReturnType<typeof import(\'./state.js\').createState>} state */\n'}export const createActions = (state${typed ? ': ReturnType<typeof createState>' : ''}) => ({ bindings: { count: state.count }, actions: { increment: () => state.count.set(state.count.get() + 1) } });
+`,
+    [`src/foundation/shell/parts/badge/unit.${ext}`]: `import { defineUnit } from '${runtime}/units';
+import { createState } from './state.${ext}';
+import { createActions } from './actions.${ext}';
+import screen from '../../../../.hesh-generated/BadgeScreen.js';
+export const createBadgeUnit = () => defineUnit({ state: createState, actions: createActions, screen });
+`,
+    'src/foundation/shell/parts/badge/screen.html': '<aside><p>Nested Hesh part: {count}</p><button h-action="increment">Increment nested state</button></aside>\n'
+  });
+  return files;
+
+}

package/src/architecture/html.ts

@@ -2,6 +2,7 @@ import { parseFragment, type DefaultTreeAdapterMap } from 'parse5';
 import { diagnostic, type ArchitectureDiagnostic } from './diagnostics.js';
 export interface HTMLContract {
   filename: string; bindings: string[]; actions: string[];
+  parts?: string[]; allowOutlet?: boolean;
   destinations: Record<string, Record<string, string>>;
   validateBinding?: (path: string, offset: number, expected?: string, writable?: boolean) => void;
 }
@@ -49,8 +50,20 @@ export function compileHTML(source: string, contract: HTMLContract): HTMLResult
       const wholeBinding = attr.value.startsWith('{') && attr.value.endsWith('}') && !attr.value.slice(1, -1).includes('{') && !attr.value.slice(1, -1).includes('}');
       lines.push(`p.attribute(${id}, ${JSON.stringify(attr.name)}, () => ${wholeBinding ? path(attr.value.slice(1, -1), attrAt(attr.name) + 1) : interpolation(attr.value, attrAt(attr.name))});`);
     }
-    for (const name of Object.keys(attributes)) if (name.startsWith('h-') && !['h-action', 'h-bind', 'h-value', 'h-destination'].includes(name) && !name.startsWith('h-input-')) report('HESH-HTML-004', `Unsupported directive ${name}`, attrAt(name), 'Use supported directives; keyed lists/scoped templates are a later milestone.');
-    if (attributes['h-bind'] !== undefined) {
+    for (const name of Object.keys(attributes)) if (name.startsWith('h-') && !['h-action', 'h-bind', 'h-value', 'h-destination', 'h-part', 'h-outlet'].includes(name) && !name.startsWith('h-input-')) report('HESH-HTML-004', `Unsupported directive ${name}`, attrAt(name), 'Use supported directives; keyed lists/scoped templates are a later milestone.');
+    const content = ['h-bind', 'h-part', 'h-outlet'].filter(name => attributes[name] !== undefined);
+    if (content.length > 1 || (content.length && node.childNodes.length)) report('HESH-HTML-005', 'Content directives require an empty container and cannot be combined', at, 'Choose one content directive and remove children.');
+    if (attributes['h-part'] !== undefined || attributes['h-outlet'] !== undefined) {
+      if (['area','base','br','col','embed','hr','img','input','link','meta','param','source','track','wbr'].includes(node.tagName)) report('HESH-HTML-005', 'Parts and outlets require a container element', at, 'Use div, main, section or another container.');
+      if (attributes['h-part'] !== undefined) {
+        const name = attributes['h-part'];
+        if (!contract.parts?.includes(name)) report('HESH-PART-001', `Undeclared Hesh part ${name}`, at, 'Declare parts and return a Hesh Unit from parts.NAME.');
+        lines.push(`p.mountPart(${id}, state, ${JSON.stringify(name)});`);
+      } else {
+        if (!contract.allowOutlet || attributes['h-outlet'] !== '') report('HESH-PART-002', 'h-outlet is only available on standalone shell screens', at, 'Use an empty h-outlet on the persistent shell.');
+        lines.push(`p.unitOutlet(${id});`);
+      }
+    } else if (attributes['h-bind'] !== undefined) {
       if (node.childNodes.length) report('HESH-BIND-003', 'h-bind cannot also contain children', at, 'Remove the children or use text interpolation.');
       lines.push(`p.text(${id}, () => ${path(attributes['h-bind'], attrAt('h-bind'))});`);
     } else node.childNodes.forEach(child => visit(child, id));

package/src/architecture/index.ts

@@ -152,10 +152,12 @@ export function createArchitectureCompiler() {
         const target = getMember(result, operation.name.split('.'));
         if (!target || !checker.getSignaturesOfType(target, ts.SignatureKind.Call).length) error('HESH-ARCH-003', `Unresolved callable implementation ${item.node.name}.${operation.name}`, item, operation.start, 'Return this operation from the declared implementation factory.');
       }
-      else for (const block of ['bindings', 'actions']) {
+      else for (const block of ['bindings', 'actions', 'parts']) {
+        if (block === 'parts' && !list(item, block).length) continue;
         if (!getMember(result, [block])) error('HESH-BIND-002', `Presentation factory must return a ${block} object`, item);
-        for (const binding of list(item, block, true)) {
+        for (const binding of list(item, block, block !== 'parts')) {
           const target = getMember(result, [block, binding.name]);
+          if (block === 'parts' && !getMember(result, [block, binding.name, 'attach'])?.getCallSignatures().length) error('HESH-PART-001', `Part ${binding.name} must be a Hesh Unit`, item, binding.start);
           if (!target || (block === 'actions' && !checker.getSignaturesOfType(target, ts.SignatureKind.Call).length)) error(block === 'actions' ? 'HESH-ACTION-001' : 'HESH-BIND-002', `Missing ${block} implementation ${binding.name}`, item, binding.start, `Return ${block}.${binding.name} from the presentation factory.`);
         }
       }
@@ -188,7 +190,12 @@ export function createArchitectureCompiler() {
       };
       walk(syntax);
     }
-    for (const failure of [...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()]) if (failure.file && inside(canonical(failure.file.fileName), root)) diagnostics.push(diagnostic('HESH-TYPE-001', ts.flattenDiagnosticMessageText(failure.messageText, '\n'), failure.file.fileName, failure.file.text, failure.start ?? 0, 'Correct the implementation type/syntax error.'));
+    for (const failure of [...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()]) if (failure.file && inside(canonical(failure.file.fileName), root)) {
+      // Declared screen modules are produced by this compilation, including on a fresh checkout.
+      const missing = failure.code === 2307 && failure.file.text.slice(failure.start, (failure.start ?? 0) + (failure.length ?? 0)).replace(/^['"]|['"]$/g, '');
+      const generatedScreen = missing && presentations.some(item => canonical(resolve(dirname(failure.file!.fileName), missing)) === canonical(join(outDir, `${item.node.name}.js`)));
+      if (!generatedScreen) diagnostics.push(diagnostic('HESH-TYPE-001', ts.flattenDiagnosticMessageText(failure.messageText, '\n'), failure.file.fileName, failure.file.text, failure.start ?? 0, 'Correct the implementation type/syntax error.'));
+    }
     const schemas: Record<string, Record<string, string>> = Object.create(null), urls = new Map<string, Located>();
     const graph: ProjectResult['graph'] = { domains: domains.map(d => ({ name: d.node.name, exposes: list(d, 'exposes').map(e => e.name), consumes: list(d, 'consumes').map(e => e.name) })), destinations: [], links: [] };
     const presentationFor = new Map<Located, Located>();
@@ -215,11 +222,11 @@ export function createArchitectureCompiler() {
       schemas[item.node.name] = inputs;
     }
     const outputs: Record<string, string> = {}, htmlModules = new Map<Located, string>();
-    for (const item of new Set(presentationFor.values())) {
+    for (const item of presentations) {
       const html = canonical(resolve(dirname(item.file), field(item, 'html'))), stylePath = field(item, 'styles', false);
       if (!isFile(html) || !html.endsWith('.html') || !inside(html, canonical(dirname(item.file)))) { error('HESH-HTML-001', `Missing or private presentation HTML ${html}`, item); continue; }
       const source = read(html), factory = resolvedFactories.get(item);
-      const compiled = compileHTML(source, { filename: html, bindings: list(item, 'bindings', true).map(e => e.name), actions: list(item, 'actions', true).map(e => e.name), destinations: schemas,
+      const compiled = compileHTML(source, { filename: html, bindings: list(item, 'bindings', true).map(e => e.name), actions: list(item, 'actions', true).map(e => e.name), parts: list(item, 'parts').map(e => e.name), allowOutlet: ![...presentationFor.values()].includes(item), destinations: schemas,
         validateBinding(path, offset, expected, writable) {
           if (!factory) return;
           const type = getMember(factory.result, ['bindings', ...path.split('.')], true);
@@ -245,6 +252,7 @@ export function createArchitectureCompiler() {
         else { files.add(style); css = `import ${JSON.stringify(modulePath(output, style))};\n`; }
       }
       outputs[output] = css + compiled.code;
+      outputs[output.replace(/\.js$/, '.d.ts')] = "import type { PresentationState } from '@heshammesalam/heshjs/presentation';\nexport default function render(parent: Node, state: PresentationState, destinations?: object): void;\n";
     }
     const output = join(outDir, 'app.js'), types = join(outDir, 'app.d.ts');
     const js = ["import { createGraphApplication, createDomainGraph } from '@heshammesalam/heshjs/destinations';"];

package/src/destinations/index.ts

@@ -1,5 +1,5 @@
 import { createRouter } from '../router/index.js';
-import { defineModule, useController, type RouteLocation } from '../hmvc/index.js';
+import { defineModule, useController, useModule, withModuleContext, type RouteLocation } from '../hmvc/index.js';
 import { createDomainGraph, ClientPolicyDenied, type DomainDefinition, type DomainOptions, type DomainGraph } from '../domains/index.js';
 import { signal, effect, onCleanup, scope, type Disposer } from '../reactivity/index.js';
 import { mount, element, text } from '../dom/index.js';
@@ -85,6 +85,7 @@ export function createGraphApplication(definitions: readonly DomainDefinition[],
     model: context => context.route,
     controller: route => route,
     view(parent) {
+      const parentContext = useModule();
       const route = useController<{ get(): RouteLocation }>();
       effect(() => {
         const location = route.get();
@@ -106,7 +107,7 @@ export function createGraphApplication(definitions: readonly DomainDefinition[],
           const owned = scope(() => {
             const state = resources.create({ input, domains: graph.forDomain(page.owner), location, signal: abort.signal });
             if (state && typeof (state as unknown as { then?: unknown }).then === 'function') throw new Error('Presentation factories must be synchronous; use the provided AbortSignal for async work');
-            mount(() => resources.view(parent, state, destinations), parent, { onError: report });
+            mount(() => withModuleContext(parentContext, () => resources.view(parent, state, destinations)), parent, { onError: report });
           });
           dispose = owned.dispose;
           if (abort.signal.aborted) { dispose(); return; }

package/src/heshjs/index.ts

@@ -2,3 +2,5 @@ export { signal, effect, derived, batch, scope, onCleanup, untrack } from '../re
 export type { Signal, Disposer } from '../reactivity/index.js';
 export { mount, element, text, attribute, listen, input, component } from '../dom/index.js';
 export type { Component, MountOptions } from '../dom/index.js';
+export { defineUnit, useUnit, useUnitState, useUnitActions } from '../units/index.js';
+export type { HeshUnit, UnitDefinition } from '../units/index.js';

package/src/hmvc/index.ts

@@ -30,6 +30,13 @@ export interface AppModule {
 }
 let current: { context: ModuleContext; outlet?: Node } | undefined;
 
+/** Restore a captured parent context while mounting an asynchronously loaded screen. */
+export function withModuleContext<T>(context: ModuleContext, run: () => T): T {
+  const previous = current;
+  current = { context };
+  try { return run(); } finally { current = previous; }
+}
+
 export function useModule<M = unknown, C = unknown>(): ModuleContext<M, C> {
   if (!current) throw new Error('Module context is only available during a module view mount');
   return current.context as ModuleContext<M, C>;

package/src/parser/index.ts

@@ -132,7 +132,7 @@ export function parse(source: string, filename = 'component.hesh'): ParsedModule
     const result: Contract = { kind: kind.text as Contract['kind'], name: name.text, start: kind.start, end: 0, fields: Object.create(null), blocks: Object.create(null) };
     const schemas: Record<Contract['kind'], Record<string, string>> = {
       domain: { implementation: 'string', owns: 'list', exposes: 'list', consumes: 'list', access: 'map' },
-      presentation: { html: 'string', logic: 'string', styles: 'string', bindings: 'list', actions: 'list' },
+      presentation: { html: 'string', logic: 'string', styles: 'string', bindings: 'list', actions: 'list', parts: 'list' },
       destination: { url: 'string', input: 'map', presentation: 'identifier', access: 'string' },
       application: { domains: 'list', destinations: 'list' }
     };

package/src/presentation/index.ts

@@ -1,7 +1,9 @@
 import { effect } from '../reactivity/index.js';
 import { nativeElement as element, text, attribute, listen } from '../dom/index.js';
 export { element, text, attribute, listen };
-export interface PresentationState { bindings: Record<string, unknown>; actions: Record<string, (event: Event) => unknown> }
+export { mountPart, unitOutlet } from '../units/index.js';
+import type { HeshUnit } from '../units/index.js';
+export interface PresentationState { bindings: Record<string, unknown>; actions: Record<string, (event: Event) => unknown>; parts?: Record<string, HeshUnit> }
 export function readBinding(bindings: Record<string, unknown>, path: string): unknown {
   const unwrap = (value: unknown): unknown => {
     if (typeof value === 'function') return value();

package/src/units/index.ts

@@ -0,0 +1,23 @@
+import { defineModule, useController, useModule, Outlet, type AppModule, type ModuleContext } from '../hmvc/index.js';
+import type { PresentationState } from '../presentation/index.js';
+
+export type HeshUnit = AppModule;
+export interface UnitDefinition<S, A extends PresentationState> {
+  state(context: Pick<ModuleContext, 'route' | 'parent'>): S;
+  actions(state: S, context: Pick<ModuleContext, 'route' | 'parent'>): A;
+  screen(parent: Node, state: A, destinations?: object): void;
+  destinations?: object;
+}
+/** Hesh naming over the hierarchical, scope-owned module lifecycle. */
+export function defineUnit<S, A extends PresentationState>(definition: UnitDefinition<S, A>): HeshUnit {
+  return defineModule({ model: definition.state, controller: definition.actions,
+    view(parent) { definition.screen(parent, useController<A>(), definition.destinations); }
+  });
+}
+export function mountPart(parent: Node, state: PresentationState, name: string): void {
+  const part = state.parts?.[name];
+  if (!part || typeof part.attach !== 'function') throw new Error(`Missing Hesh part ${name}`);
+  const context = useModule();
+  part.attach(parent, context.route.get(), context);
+}
+export { Outlet as unitOutlet, useModule as useUnit, useModel as useUnitState, useController as useUnitActions } from '../hmvc/index.js';