@aihu/compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fellwork
+
+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,33 @@
+# @aihu/compiler
+
+> Single File Component (.aihu) compiler — Rust binary + JS glue.
+
+⚠ **Native binary required.** This package downloads a pre-built `aihu-compile` binary at install time via `js/postinstall.ts` (see [WASM.md](https://github.com/fellwork/aihu/blob/main/packages/compiler/WASM.md)). Binaries are published per-platform from the `release.yml` workflow on every `v*` tag. SHA256-verified per arch-4 §4.3.
+
+Part of the [aihu](https://github.com/fellwork/aihu) framework — agentic discovery and interaction, for human purpose.
+
+## Install
+
+```bash
+npm install @aihu/compiler
+# or
+bun add @aihu/compiler
+```
+
+## Usage
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { aihuCompiler } from '@aihu/compiler';
+
+export default defineConfig({ plugins: [aihuCompiler()] });
+```
+
+## Status
+
+Early access (`0.1.x`). API may evolve before v1.1 GA. See the [v1.1 roadmap](https://github.com/fellwork/aihu/tree/main/docs/roadmap) for stability commitments.
+
+## License
+
+MIT — see [LICENSE](https://github.com/fellwork/aihu/blob/main/LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+//#region js/index.d.ts
+interface VitePlugin {
+  readonly name: string;
+  enforce?: 'pre' | 'post';
+  transform?: (code: string, id: string) => Promise<{
+    code: string;
+    map: null;
+  }> | {
+    code: string;
+    map: null;
+  } | null | undefined;
+}
+/**
+ * Options for `aihuCompilerPlugin()` (Plan 3.3 — Islands).
+ */
+interface AihuCompilerPluginOptions {
+  /**
+   * When `true` (default), components classified as `'static'` by
+   * `_classifyIsland()` are emitted with a minimal HTML-only registration
+   * shim that ships **zero** `@aihu/runtime` and `@aihu/signals` JS to
+   * the browser. Components classified as `'interactive'` retain the
+   * full runtime path.
+   *
+   * Setting `islands: false` opts every component back into the unified
+   * runtime path (Plan 3.2 baseline behaviour).
+   */
+  islands?: boolean;
+  /**
+   * Project-wide shadow-DOM mode applied to every `.aihu` SFC compiled
+   * by this plugin instance. When set, the plugin post-processes the
+   * compiled JS to inject `, { shadowMode: '<mode>' }` as the third arg
+   * to the emitted `defineElement(tag, defineComponent(...))` call.
+   *
+   * - `'open'`   — default browser behaviour (shadow root, externally readable).
+   * - `'closed'` — shadow root, externally hidden.
+   * - `'none'`   — **no shadow root.** The component mounts into its own
+   *               element. Required for global utility-class CSS frameworks
+   *               like Tailwind, UnoCSS, Pico that rely on the cascade.
+   *
+   * Per-component override is not yet supported via SFC syntax (post-v1).
+   * For per-component control today, hand-author the component with
+   * `defineElement(tag, Ctor, { shadowMode: '...' })`.
+   */
+  shadowMode?: 'open' | 'closed' | 'none';
+}
+/**
+ * Inject `{ shadowMode: '...' }` as the third argument to the emitted
+ * `defineElement('tag', defineComponent(...))` call. The compiler emits
+ * exactly two arguments today; this rewrites the closing of the
+ * defineElement call to include the options object. Idempotent — leaves
+ * code untouched when the closer is not in the expected shape.
+ *
+ * @internal
+ */
+declare function _injectShadowMode(code: string, mode: 'open' | 'closed' | 'none'): string;
+/**
+ * Classify the compiled output of a single `.aihu` module as either a
+ * **static** island (no reactive state — purely declarative DOM) or an
+ * **interactive** island (uses the signals reactivity system).
+ *
+ * The heuristic is intentionally conservative: any source-level reference
+ * to `signal(`, `computed(`, `effect(`, or `setSignal(` flips the file to
+ * `'interactive'`. False positives (e.g. a string literal containing
+ * `signal(`) are tolerable — they only forfeit the static-island
+ * optimisation. False negatives are forbidden: a static-classified file
+ * MUST NOT depend on the signals runtime at execution time.
+ *
+ * Plan 3.3 / acceptance criterion 1.
+ *
+ * @internal
+ */
+declare function _classifyIsland(compiledCode: string): 'static' | 'interactive';
+/**
+ * Rewrite an interactive-island module so its `connectedCallback` waits
+ * for the element to scroll into view before mounting. Plan 3.3 — applied
+ * only when the consumer adds `defer` to the custom element tag (e.g.
+ * `<my-counter defer>`); the runtime helper checks the attribute and
+ * either mounts immediately or registers an `IntersectionObserver`.
+ *
+ * Implementation: the helper is added as a `_hydrateOnVisible` import
+ * from `@aihu/runtime`, and the compiler-emitted `defineElement(...)`
+ * call is wrapped in a `defineElement` that intercepts `connectedCallback`
+ * to honour the `defer` attribute.
+ *
+ * The whole indirection is tree-shaken when no `.aihu` module reaches
+ * this branch, because `_hydrateOnVisible` is exported from its own
+ * sibling module inside `@aihu/runtime`.
+ *
+ * @internal
+ */
+declare function _buildDeferredHydration(compiledCode: string, elementTag: string): string;
+/**
+ * Build a static-island shim for a compiled module.
+ *
+ * The compiled module emitted by the Rust codegen has the shape:
+ *
+ *   import { branch, leaf, slot } from '@aihu/arbor'
+ *   import { defineComponent, defineElement } from '@aihu/runtime'
+ *   defineElement('tag', defineComponent((_ctx) => { return <tree> }))
+ *
+ * For a static island we know `<tree>` contains no `signal(`/`computed(`
+ * calls. We can therefore:
+ *
+ *   1. Drop the `@aihu/runtime` import (saves ~600 B gz of defineComponent
+ *      + defineElement + bootstrap glue).
+ *   2. Replace `defineElement(tag, defineComponent(setup))` with a tiny
+ *      inline class that mounts the tree directly via `mount()` (which the
+ *      arbor barrel already exports).
+ *   3. Tag the file with a `// SCRIBE_STATIC_ISLAND` comment so consumers
+ *      can audit which routes shipped zero-JS-runtime.
+ *
+ * Falls back to the original code if the regex shape does not match
+ * (defensive: a future compiler change must opt back into static-island
+ * emission explicitly rather than silently break).
+ *
+ * @internal
+ */
+declare function _buildStaticIsland(compiledCode: string, elementTag: string): string;
+/**
+ * Compile a .aihu source string to TypeScript.
+ * map is null — source maps are deferred to v1 (OQ-C8)
+ */
+declare function transform(source: string, id: string): {
+  code: string;
+  map: null;
+};
+/**
+ * Inject `_setMount(mount)` + `_setSignal(signal)` auto-wiring into a compiled
+ * `.aihu` module. Adds the necessary symbols to existing imports and inserts
+ * the boot calls right after the last `import` statement.
+ *
+ * @internal
+ */
+declare function _injectAutoWiring(code: string): string;
+/**
+ * Vite plugin that compiles .aihu files to TypeScript during build and dev.
+ *
+ * Use `enforce: 'pre'` so the hook fires before Vite/Rollup's built-in
+ * parsers attempt to process the raw .aihu content as JavaScript.
+ *
+ * @example
+ * // vite.config.ts
+ * import { aihuCompilerPlugin } from '@aihu/compiler'
+ * export default { plugins: [aihuCompilerPlugin()] }
+ *
+ * **Known Limitation — Bun + Rollup4 ESM incompatibility (v0):**
+ *
+ * `bun vite build` fails in the `fixtures/vite-counter` fixture with two
+ * cascading errors:
+ *
+ * 1. **Missing devDependency:** `vite` is declared only as an optional
+ *    `peerDependency` in `packages/compiler/package.json`. Bun does not
+ *    install optional peers automatically, so `bun vite build` exits
+ *    immediately with `Cannot find package 'vite'`.
+ *
+ * 2. **Bun + Rollup4 bridge:** Even with Vite installed, Bun processes
+ *    `vite.config.ts` through its own internal bundler before handing off
+ *    to Rollup4. When `@aihu/compiler` is resolved from the workspace
+ *    symlink (`dist/index.js`), Bun's ESM loader evaluates the module at
+ *    config-load time. The subprocess call inside `transform()` depends on
+ *    the Rust binary being at `../bin/aihu-compile` relative to `dist/`
+ *    (written by the postinstall hook). In a dev workspace where postinstall
+ *    has not run, this path does not exist and `execFileSync` throws. Bun surfaces
+ *    the error as a config-load failure, not a per-file transform error,
+ *    causing the entire build to abort before any `.aihu` file is
+ *    processed.
+ *
+ * **Workaround (v0):** Use `bun run integrate.ts` directly from
+ * `packages/compiler/fixtures/vite-counter/`. This script calls
+ * `transform()` from `@aihu/compiler` without involving Vite or Rollup.
+ * Preconditions: (1) `cargo build --release` in `packages/compiler/`,
+ * (2) `bun install` at the repo root.
+ *
+ * **v1 resolution:** Add `vite` as a `devDependency` in
+ * `packages/compiler/package.json`; add a WASM or pre-built binary
+ * strategy so the Rust binary is bundled with the npm package and does not
+ * require a separate `cargo build --release` step.
+ */
+declare function aihuCompilerPlugin(options?: AihuCompilerPluginOptions): VitePlugin;
+//#endregion
+export { AihuCompilerPluginOptions, _buildDeferredHydration, _buildStaticIsland, _classifyIsland, _injectAutoWiring, _injectShadowMode, aihuCompilerPlugin, transform };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../js/index.ts"],"mappings":";UAoBU,UAAA;EAAA,SACC,IAAA;EACT,OAAA;EACA,SAAA,IACE,IAAA,UACA,EAAA,aACG,OAAA;IAAU,IAAA;IAAc,GAAA;EAAA;IAAiB,IAAA;IAAc,GAAA;EAAA;AAAA;;;;UAM7C,yBAAA;EANgD;;AAMjE;;;;;AAyCA;;;EA9BE,OAAA;EA8B8E;AA0BhF;;;;;AA8GA;;;;;AA2GA;;;;;EA/PE,UAAA;AAAA;;;;;;;;;AAmUF;iBAvTgB,iBAAA,CAAkB,IAAA,UAAc,IAAA;;;;AA2bhD;;;;;;;;;;;;;iBAjagB,eAAA,CAAgB,YAAA;;;;;;;;;;;;;;;;;;;iBA8GhB,uBAAA,CAAwB,YAAA,UAAsB,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2G9C,kBAAA,CAAmB,YAAA,UAAsB,UAAA;;;;;iBAiDzC,SAAA,CAAU,MAAA,UAAgB,EAAA;EAAe,IAAA;EAAc,GAAA;AAAA;;;;;;;;iBAmBvD,iBAAA,CAAkB,IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoIlB,kBAAA,CAAmB,OAAA,GAAU,yBAAA,GAA4B,UAAA"}

package/dist/index.js

@@ -0,0 +1,43 @@
+import{execFileSync as e}from"node:child_process";import{basename as t,dirname as n,resolve as r}from"node:path";import{fileURLToPath as i}from"node:url";const a=process.platform===`win32`?`.exe`:``,o=process.env.SCRIBE_COMPILE_BIN??r(n(i(import.meta.url)),`../bin/aihu-compile${a}`);function s(e,t){return e.replace(/(defineElement\(\s*['"][^'"]+['"]\s*,\s*defineComponent\([^]*\))\s*\)/,(e,n)=>`${n}, { shadowMode: '${t}' })`)}function c(e){return/\b(?:signal|computed|effect|setSignal)\s*\(/.test(e)?`interactive`:`static`}function l(e){let t=/defineElement\(\s*['"]([^'"]+)['"]/m.exec(e);return t?t[1]??null:null}function u(e,t){let n=e.replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/runtime'/,(e,t)=>{let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`_hmrReplace`)||n.push(`_hmrReplace`),`import { ${n.join(`, `)} } from '@aihu/runtime'`}).replace(/\bdefineComponent\(/,`defineComponent(__aihu_setup__ = `),r=`
+export { __aihu_setup__ as default }
+
+if (typeof __DEV__ !== 'undefined' && __DEV__ && import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (!newModule) return
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const newSetup = (newModule as any)['default']
+    if (typeof newSetup !== 'function') return
+    document.querySelectorAll(${JSON.stringify(t)}).forEach((el) => {
+      _hmrReplace(el as HTMLElement, newSetup)
+    })
+  })
+}
+`;return`let __aihu_setup__: ((ctx: any) => any) | undefined
+`+n+r}function d(e,t){let n=e.replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/runtime'/,(e,t)=>{let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`_hydrateOnVisible`)||n.push(`_hydrateOnVisible`),`import { ${n.join(`, `)} } from '@aihu/runtime'`}),r=n.replace(/defineElement\(\s*('[^']+'|"[^"]+")\s*,\s*defineComponent\(/,(e,t)=>`defineElement(${t}, __aihu_wrap_defer__(defineComponent(`);if(r===n)return e;let i=r.replace(/\)\s*\)\s*\nexport\s/,`)))
+export `);return i===r&&(i=r.replace(/\)\s*\)\s*$/,`)))
+`)),i===r?e:`
+// Plan 3.3 (Islands) — defer attribute support. Wraps the constructor
+// returned by defineComponent so instances bearing the \`defer\` attribute
+// hydrate lazily via IntersectionObserver. Bare instances retain the
+// eager Plan 3.2 hydration path.
+function __aihu_wrap_defer__<T extends typeof HTMLElement>(Ctor: T): T {
+  const orig = (Ctor.prototype as unknown as { connectedCallback?: () => void }).connectedCallback
+  if (typeof orig !== 'function') return Ctor
+  ;(Ctor.prototype as unknown as { connectedCallback: () => void }).connectedCallback = function (this: HTMLElement) {
+    if (this.hasAttribute('defer')) {
+      _hydrateOnVisible(this, () => orig.call(this))
+    } else {
+      orig.call(this)
+    }
+  }
+  return Ctor
+}
+`+i}function f(e,t){if(!/defineElement\(\s*['"][^'"]+['"]\s*,\s*defineComponent\(/.test(e))return e;let n=e.replace(/^\s*import\s*\{[^}]*\}\s*from\s*'@aihu\/runtime'\s*;?\s*$/m,``).replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/arbor'/,(e,t)=>{let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`mount`)||n.push(`mount`),`import { ${n.join(`, `)} } from '@aihu/arbor'`}),r=JSON.stringify(t);return`// SCRIBE_STATIC_ISLAND — zero @aihu/runtime references\n${n.replace(/defineElement\(\s*['"][^'"]+['"]\s*,\s*defineComponent\(/,`customElements.define(${r}, class extends HTMLElement {\n  connectedCallback() {\n    const root = this.attachShadow({ mode: 'open' })\n    const __aihu_setup__ = (`).replace(/\)\s*\)\s*$/,`)
+    mount(__aihu_setup__({ host: root, element: this }), root)
+  }
+})
+`)}`}function p(n,r){return{code:e(o,[`--stdin`,`--tag`,t(r,`.aihu`),`--path`,r],{input:n,encoding:`utf8`}),map:null}}function m(e){let t;t=e.includes(`from '@aihu/arbor'`)?e.replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/arbor'/,(e,t)=>{let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`mount`)||n.push(`mount`),`import { ${n.join(`, `)} } from '@aihu/arbor'`}):`import { mount } from '@aihu/arbor'
+`+e,/import\s+\{[^}]*\}\s+from\s+'@aihu\/signals'/.test(t)?t=t.replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/signals'/,(e,t)=>{if(e.startsWith(`import type`))return e;let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`signal`)||n.push(`signal`),`import { ${n.join(`, `)} } from '@aihu/signals'`}):/import.*from\s*'@aihu\/signals'/.test(t)?/import\s+type\s+\{[^}]*\}\s+from\s+'@aihu\/signals'/.test(t)&&!t.match(/import\s+\{[^}]*\}\s+from\s+'@aihu\/signals'/)&&(t=t.replace(/(import\s+type\s+\{[^}]*\}\s+from\s+'@aihu\/signals')/,(e,t)=>`${t}\nimport { signal } from '@aihu/signals'`)):t=t.replace(/import\s*\{[^}]*\}\s*from\s*'@aihu\/arbor'/,e=>`${e}\nimport { signal } from '@aihu/signals'`),t=t.replace(/import\s*\{([^}]*)\}\s*from\s*'@aihu\/runtime'/,(e,t)=>{let n=t.split(`,`).map(e=>e.trim()).filter(Boolean);return n.includes(`_setMount`)||n.push(`_setMount`),n.includes(`_setSignal`)||n.push(`_setSignal`),`import { ${n.join(`, `)} } from '@aihu/runtime'`});let n=t.split(`
+`),r=-1;for(let e=n.length-1;e>=0;e--){let t=(n[e]??``).trim();if(t.startsWith(`import `)||t.startsWith(`import{`)){r=e;break}}return r!==-1&&(n.splice(r+1,0,`_setMount(mount)`,`_setSignal(signal)`,``),t=n.join(`
+`)),t}function h(e){let t=e?.islands!==!1,n=e?.shadowMode;return{name:`aihu-compiler`,enforce:`pre`,transform(e,r){let i=r.split(`?`)[0];if(i.endsWith(`.aihu`))return(async()=>{let r=p(e,i),a=n==null?r.code:s(r.code,n),o=l(a),h;t&&o!==null&&c(a)===`static`?h=f(a,o):o===null?(h=a,h=m(h)):(h=u(a,o),h=d(h,o),h=m(h));try{let{transformWithEsbuild:e}=await import(`vite`);return{code:(await e(h,`component.ts`,{target:`esnext`,sourcemap:!1})).code,map:null}}catch{return{code:h,map:null}}})()}}}export{d as _buildDeferredHydration,f as _buildStaticIsland,c as _classifyIsland,m as _injectAutoWiring,s as _injectShadowMode,h as aihuCompilerPlugin,p as transform};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../js/index.ts"],"sourcesContent":["/**\n * @aihu/compiler — TypeScript wrapper around the aihu-compile Rust binary.\n *\n * Exports:\n *   transform(source, id)    — compile a single .aihu file to TypeScript\n *   aihuCompilerPlugin()   — Vite plugin that wires transform() into the build\n */\nimport { execFileSync } from 'node:child_process'\nimport { basename, dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n// Binary resolution: env var override, fallback to the bin/ directory written\n// by the postinstall hook (packages/compiler/bin/aihu-compile[.exe]).\nconst ext = process.platform === 'win32' ? '.exe' : ''\nconst binPath: string =\n  process.env.SCRIBE_COMPILE_BIN ??\n  resolve(dirname(fileURLToPath(import.meta.url)), `../bin/aihu-compile${ext}`)\n\n// Minimal VitePlugin interface — avoids importing from 'vite' at compile time.\n// Structurally compatible with Vite's Plugin type.\ninterface VitePlugin {\n  readonly name: string\n  enforce?: 'pre' | 'post'\n  transform?: (\n    code: string,\n    id: string,\n  ) => Promise<{ code: string; map: null }> | { code: string; map: null } | null | undefined\n}\n\n/**\n * Options for `aihuCompilerPlugin()` (Plan 3.3 — Islands).\n */\nexport interface AihuCompilerPluginOptions {\n  /**\n   * When `true` (default), components classified as `'static'` by\n   * `_classifyIsland()` are emitted with a minimal HTML-only registration\n   * shim that ships **zero** `@aihu/runtime` and `@aihu/signals` JS to\n   * the browser. Components classified as `'interactive'` retain the\n   * full runtime path.\n   *\n   * Setting `islands: false` opts every component back into the unified\n   * runtime path (Plan 3.2 baseline behaviour).\n   */\n  islands?: boolean\n\n  /**\n   * Project-wide shadow-DOM mode applied to every `.aihu` SFC compiled\n   * by this plugin instance. When set, the plugin post-processes the\n   * compiled JS to inject `, { shadowMode: '<mode>' }` as the third arg\n   * to the emitted `defineElement(tag, defineComponent(...))` call.\n   *\n   * - `'open'`   — default browser behaviour (shadow root, externally readable).\n   * - `'closed'` — shadow root, externally hidden.\n   * - `'none'`   — **no shadow root.** The component mounts into its own\n   *               element. Required for global utility-class CSS frameworks\n   *               like Tailwind, UnoCSS, Pico that rely on the cascade.\n   *\n   * Per-component override is not yet supported via SFC syntax (post-v1).\n   * For per-component control today, hand-author the component with\n   * `defineElement(tag, Ctor, { shadowMode: '...' })`.\n   */\n  shadowMode?: 'open' | 'closed' | 'none'\n}\n\n/**\n * Inject `{ shadowMode: '...' }` as the third argument to the emitted\n * `defineElement('tag', defineComponent(...))` call. The compiler emits\n * exactly two arguments today; this rewrites the closing of the\n * defineElement call to include the options object. Idempotent — leaves\n * code untouched when the closer is not in the expected shape.\n *\n * @internal\n */\nexport function _injectShadowMode(code: string, mode: 'open' | 'closed' | 'none'): string {\n  // Match the trailing `))` that closes `defineElement(tag, defineComponent(setup))`.\n  // The compiler always emits this exact two-paren close as the final tokens of\n  // the defineElement call — we anchor on it and append the options object.\n  // biome-ignore lint/correctness/noEmptyCharacterClassInRegex: [^] is valid JS — matches any char including newlines\n  const re = /(defineElement\\(\\s*['\"][^'\"]+['\"]\\s*,\\s*defineComponent\\([^]*\\))\\s*\\)/\n  const replaced = code.replace(re, (_m, inner: string) => `${inner}, { shadowMode: '${mode}' })`)\n  return replaced\n}\n\n/**\n * Classify the compiled output of a single `.aihu` module as either a\n * **static** island (no reactive state — purely declarative DOM) or an\n * **interactive** island (uses the signals reactivity system).\n *\n * The heuristic is intentionally conservative: any source-level reference\n * to `signal(`, `computed(`, `effect(`, or `setSignal(` flips the file to\n * `'interactive'`. False positives (e.g. a string literal containing\n * `signal(`) are tolerable — they only forfeit the static-island\n * optimisation. False negatives are forbidden: a static-classified file\n * MUST NOT depend on the signals runtime at execution time.\n *\n * Plan 3.3 / acceptance criterion 1.\n *\n * @internal\n */\nexport function _classifyIsland(compiledCode: string): 'static' | 'interactive' {\n  // Match call sites of the four reactive primitives. Use word-boundary\n  // anchors so identifiers like `mySignal(` or `__effect(` do not trip the\n  // heuristic. The `(` is required so that bare imports of the names in an\n  // unused `import { signal }` line do not flip an otherwise-static module.\n  return /\\b(?:signal|computed|effect|setSignal)\\s*\\(/.test(compiledCode) ? 'interactive' : 'static'\n}\n\n/**\n * Extract the custom element tag name from compiler-emitted code.\n * The compiler always emits `defineElement('tag-name', ...)` as the\n * first call — pull the first string literal argument.\n * Returns `null` if no `defineElement` call is found.\n * @internal\n */\nfunction _extractElementTag(code: string): string | null {\n  const m = /defineElement\\(\\s*['\"]([^'\"]+)['\"]/m.exec(code)\n  return m ? (m[1] ?? null) : null\n}\n\n/**\n * Instrument a compiled `.aihu` module with HMR support.\n *\n * The compiler always emits:\n *\n *   import { defineComponent, defineElement } from '@aihu/runtime'\n *   defineElement('tag', defineComponent((_ctx) => { ... }))\n *\n * This function:\n *\n *  1. Adds `_hmrReplace` to the `@aihu/runtime` import.\n *  2. Prepends a module-level slot variable `__aihu_setup__`.\n *  3. Rewrites the single `defineComponent(` call so the setup function\n *     is captured via an assignment expression:\n *     `defineComponent(__aihu_setup__ = ` (valid JS; assignment has\n *     lower precedence than arrow fn, so `defineComponent` still\n *     receives the function as its argument).\n *  4. Appends `export { __aihu_setup__ as default }` so that Vite's\n *     `import.meta.hot.accept` callback receives the new setup via\n *     `newModule.default` on hot reload.\n *  5. Appends the `import.meta.hot.accept` block, gated on `__DEV__`.\n *\n * The `__DEV__` guard ensures production bundlers (where they replace\n * `__DEV__` with `false`) dead-code-eliminate the entire HMR block.\n *\n * @internal\n */\nfunction _buildHmrCode(compiledCode: string, elementTag: string): string {\n  // Step 1 — add _hmrReplace to the @aihu/runtime import.\n  const withImport = compiledCode.replace(\n    /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/runtime'/,\n    (_m, imports: string) => {\n      const parts = imports\n        .split(',')\n        .map((s) => s.trim())\n        .filter(Boolean)\n      if (!parts.includes('_hmrReplace')) parts.push('_hmrReplace')\n      return `import { ${parts.join(', ')} } from '@aihu/runtime'`\n    },\n  )\n\n  // Step 2+3 — prepend slot variable and rewrite the defineComponent call.\n  // Compiler emits exactly one `defineComponent(` followed by a function expr.\n  // Rewrite: defineComponent(fn)  →  defineComponent(__aihu_setup__ = fn)\n  // Assignment expression evaluates to `fn`, so defineComponent still\n  // receives the setup function as its first argument unchanged.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const preamble = `let __aihu_setup__: ((ctx: any) => any) | undefined\\n`\n\n  const patchedBody = withImport.replace(/\\bdefineComponent\\(/, 'defineComponent(__aihu_setup__ = ')\n\n  const tag = JSON.stringify(elementTag)\n  // Step 4+5 — postamble with default export and HMR acceptance.\n  const postamble = `\nexport { __aihu_setup__ as default }\n\nif (typeof __DEV__ !== 'undefined' && __DEV__ && import.meta.hot) {\n  import.meta.hot.accept((newModule) => {\n    if (!newModule) return\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const newSetup = (newModule as any)['default']\n    if (typeof newSetup !== 'function') return\n    document.querySelectorAll(${tag}).forEach((el) => {\n      _hmrReplace(el as HTMLElement, newSetup)\n    })\n  })\n}\n`\n\n  return preamble + patchedBody + postamble\n}\n\n/**\n * Rewrite an interactive-island module so its `connectedCallback` waits\n * for the element to scroll into view before mounting. Plan 3.3 — applied\n * only when the consumer adds `defer` to the custom element tag (e.g.\n * `<my-counter defer>`); the runtime helper checks the attribute and\n * either mounts immediately or registers an `IntersectionObserver`.\n *\n * Implementation: the helper is added as a `_hydrateOnVisible` import\n * from `@aihu/runtime`, and the compiler-emitted `defineElement(...)`\n * call is wrapped in a `defineElement` that intercepts `connectedCallback`\n * to honour the `defer` attribute.\n *\n * The whole indirection is tree-shaken when no `.aihu` module reaches\n * this branch, because `_hydrateOnVisible` is exported from its own\n * sibling module inside `@aihu/runtime`.\n *\n * @internal\n */\nexport function _buildDeferredHydration(compiledCode: string, elementTag: string): string {\n  // Add _hydrateOnVisible to the @aihu/runtime import.\n  const withImport = compiledCode.replace(\n    /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/runtime'/,\n    (_m, imports: string) => {\n      const parts = imports\n        .split(',')\n        .map((s) => s.trim())\n        .filter(Boolean)\n      if (!parts.includes('_hydrateOnVisible')) parts.push('_hydrateOnVisible')\n      return `import { ${parts.join(', ')} } from '@aihu/runtime'`\n    },\n  )\n\n  // Wrap the class returned by defineComponent BEFORE defineElement\n  // consumes it. The HTML spec caches lifecycle callbacks at\n  // customElements.define() time, so we MUST mutate the prototype\n  // before that call — not after. We accomplish this with a synchronous\n  // helper invoked between defineComponent and defineElement.\n  //\n  // Source pattern (compiler-emitted):\n  //   defineElement('tag', defineComponent((_ctx) => { ... }))\n  //\n  // After this rewrite:\n  //   defineElement('tag', __aihu_wrap_defer__(defineComponent((_ctx) => { ... })))\n  //\n  // …with __aihu_wrap_defer__ defined in the appended preamble.\n  const patched = withImport.replace(\n    /defineElement\\(\\s*('[^']+'|\"[^\"]+\")\\s*,\\s*defineComponent\\(/,\n    (_m, tagLit: string) => `defineElement(${tagLit}, __aihu_wrap_defer__(defineComponent(`,\n  )\n  // Match the closing `))` of the defineElement call. The HMR pass may\n  // have inserted `__aihu_setup__ = ` before the inner function, but\n  // the trailing `))` shape is unchanged. Replace exactly one occurrence\n  // by anchoring on end-of-string trim; bail if the shape does not match.\n  if (patched === withImport) {\n    // The expected `defineElement(<tag>, defineComponent(` shape was not\n    // present (e.g. compiler output changed). Skip defer wrapping rather\n    // than emit broken code.\n    return compiledCode\n  }\n  // Add a trailing `)` to balance the extra `(` from __aihu_wrap_defer__.\n  // Source shape after _buildHmrCode is:\n  //   defineElement('tag', defineComponent(__aihu_setup__ = (_ctx) => {...}))\n  //   export { __aihu_setup__ as default }\n  //   if (typeof __DEV__ !== ...) { ... }\n  // We must close BEFORE the export line. Match the first `))` followed\n  // by a newline and `export` (or end-of-string for the unwrapped case).\n  let balanced = patched.replace(/\\)\\s*\\)\\s*\\nexport\\s/, ')))\\nexport ')\n  if (balanced === patched) {\n    // No HMR postamble — the `))` is at end-of-string.\n    balanced = patched.replace(/\\)\\s*\\)\\s*$/, ')))\\n')\n  }\n  if (balanced === patched) {\n    // Could not find the matching `))` — bail out.\n    return compiledCode\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const helper = `\n// Plan 3.3 (Islands) — defer attribute support. Wraps the constructor\n// returned by defineComponent so instances bearing the \\`defer\\` attribute\n// hydrate lazily via IntersectionObserver. Bare instances retain the\n// eager Plan 3.2 hydration path.\nfunction __aihu_wrap_defer__<T extends typeof HTMLElement>(Ctor: T): T {\n  const orig = (Ctor.prototype as unknown as { connectedCallback?: () => void }).connectedCallback\n  if (typeof orig !== 'function') return Ctor\n  ;(Ctor.prototype as unknown as { connectedCallback: () => void }).connectedCallback = function (this: HTMLElement) {\n    if (this.hasAttribute('defer')) {\n      _hydrateOnVisible(this, () => orig.call(this))\n    } else {\n      orig.call(this)\n    }\n  }\n  return Ctor\n}\n`\n  void elementTag\n  return helper + balanced\n}\n\n/**\n * Build a static-island shim for a compiled module.\n *\n * The compiled module emitted by the Rust codegen has the shape:\n *\n *   import { branch, leaf, slot } from '@aihu/arbor'\n *   import { defineComponent, defineElement } from '@aihu/runtime'\n *   defineElement('tag', defineComponent((_ctx) => { return <tree> }))\n *\n * For a static island we know `<tree>` contains no `signal(`/`computed(`\n * calls. We can therefore:\n *\n *   1. Drop the `@aihu/runtime` import (saves ~600 B gz of defineComponent\n *      + defineElement + bootstrap glue).\n *   2. Replace `defineElement(tag, defineComponent(setup))` with a tiny\n *      inline class that mounts the tree directly via `mount()` (which the\n *      arbor barrel already exports).\n *   3. Tag the file with a `// SCRIBE_STATIC_ISLAND` comment so consumers\n *      can audit which routes shipped zero-JS-runtime.\n *\n * Falls back to the original code if the regex shape does not match\n * (defensive: a future compiler change must opt back into static-island\n * emission explicitly rather than silently break).\n *\n * @internal\n */\nexport function _buildStaticIsland(compiledCode: string, elementTag: string): string {\n  // Confirm the shape we expect: a single defineElement(...) call wrapping\n  // a single defineComponent(...) call. Bail out otherwise.\n  const callRe = /defineElement\\(\\s*['\"][^'\"]+['\"]\\s*,\\s*defineComponent\\(/\n  if (!callRe.test(compiledCode)) return compiledCode\n\n  // Strip the `@aihu/runtime` import line entirely — static islands\n  // don't reference defineComponent/defineElement after the rewrite.\n  const withoutRuntimeImport = compiledCode.replace(\n    /^\\s*import\\s*\\{[^}]*\\}\\s*from\\s*'@aihu\\/runtime'\\s*;?\\s*$/m,\n    '',\n  )\n\n  // Ensure `mount` is imported from @aihu/arbor (it already exposes\n  // branch/leaf/slot, so we just append `mount` to the existing list).\n  const withArborMount = withoutRuntimeImport.replace(\n    /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/arbor'/,\n    (_m, imports: string) => {\n      const parts = imports\n        .split(',')\n        .map((s) => s.trim())\n        .filter(Boolean)\n      if (!parts.includes('mount')) parts.push('mount')\n      return `import { ${parts.join(', ')} } from '@aihu/arbor'`\n    },\n  )\n\n  // Replace `defineElement('tag', defineComponent((_ctx) => { ... }))`\n  // with an inline `customElements.define` whose connectedCallback mounts\n  // the static tree. The setup function is captured verbatim by replacing\n  // the wrapping calls with anonymous-IIFE bookends.\n  const tagJson = JSON.stringify(elementTag)\n  const rewritten = withArborMount\n    .replace(\n      /defineElement\\(\\s*['\"][^'\"]+['\"]\\s*,\\s*defineComponent\\(/,\n      `customElements.define(${tagJson}, class extends HTMLElement {\\n  connectedCallback() {\\n    const root = this.attachShadow({ mode: 'open' })\\n    const __aihu_setup__ = (`,\n    )\n    .replace(\n      /\\)\\s*\\)\\s*$/,\n      `)\\n    mount(__aihu_setup__({ host: root, element: this }), root)\\n  }\\n})\\n`,\n    )\n\n  return `// SCRIBE_STATIC_ISLAND — zero @aihu/runtime references\\n${rewritten}`\n}\n\n/**\n * Compile a .aihu source string to TypeScript.\n * map is null — source maps are deferred to v1 (OQ-C8)\n */\nexport function transform(source: string, id: string): { code: string; map: null } {\n  const stem = basename(id, '.aihu')\n  const code = execFileSync(binPath, ['--stdin', '--tag', stem, '--path', id], {\n    input: source,\n    encoding: 'utf8',\n  })\n  return {\n    code,\n    map: null, // source maps deferred to v1 (OQ-C8)\n  }\n}\n\n/**\n * Inject `_setMount(mount)` + `_setSignal(signal)` auto-wiring into a compiled\n * `.aihu` module. Adds the necessary symbols to existing imports and inserts\n * the boot calls right after the last `import` statement.\n *\n * @internal\n */\nexport function _injectAutoWiring(code: string): string {\n  // 1. Add `mount` to the @aihu/arbor import (or create it).\n  let result: string\n  if (code.includes(\"from '@aihu/arbor'\")) {\n    result = code.replace(\n      /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/arbor'/,\n      (_m: string, imports: string) => {\n        const parts = imports\n          .split(',')\n          .map((s) => s.trim())\n          .filter(Boolean)\n        if (!parts.includes('mount')) parts.push('mount')\n        return `import { ${parts.join(', ')} } from '@aihu/arbor'`\n      },\n    )\n  } else {\n    result = `import { mount } from '@aihu/arbor'\\n` + code\n  }\n\n  // 2. Add `signal` to the non-type @aihu/signals import (or create it).\n  // Note: `import\\s+\\{` does NOT match `import type {` (the regex needs `{` immediately\n  // after whitespace, whereas `import type {` has `type` in between).  No negation guard\n  // is needed — the replace callback below already skips `import type` lines.\n  if (/import\\s+\\{[^}]*\\}\\s+from\\s+'@aihu\\/signals'/.test(result)) {\n    // There IS a value import from signals — add `signal` if missing.\n    result = result.replace(\n      /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/signals'/,\n      (_m: string, imports: string) => {\n        // Skip type-only imports\n        if (_m.startsWith('import type')) return _m\n        const parts = imports\n          .split(',')\n          .map((s) => s.trim())\n          .filter(Boolean)\n        if (!parts.includes('signal')) parts.push('signal')\n        return `import { ${parts.join(', ')} } from '@aihu/signals'`\n      },\n    )\n  } else if (!/import.*from\\s*'@aihu\\/signals'/.test(result)) {\n    // No signals import at all — insert after arbor import\n    result = result.replace(\n      /import\\s*\\{[^}]*\\}\\s*from\\s*'@aihu\\/arbor'/,\n      (m: string) => `${m}\\nimport { signal } from '@aihu/signals'`,\n    )\n  }\n  // If only `import type { Signal }` exists, insert value import after it\n  else if (\n    /import\\s+type\\s+\\{[^}]*\\}\\s+from\\s+'@aihu\\/signals'/.test(result) &&\n    !result.match(/import\\s+\\{[^}]*\\}\\s+from\\s+'@aihu\\/signals'/)\n  ) {\n    result = result.replace(\n      /(import\\s+type\\s+\\{[^}]*\\}\\s+from\\s+'@aihu\\/signals')/,\n      (_m: string, typeImport: string) => `${typeImport}\\nimport { signal } from '@aihu/signals'`,\n    )\n  }\n\n  // 3. Add `_setMount`, `_setSignal` to the @aihu/runtime import.\n  result = result.replace(\n    /import\\s*\\{([^}]*)\\}\\s*from\\s*'@aihu\\/runtime'/,\n    (_m: string, imports: string) => {\n      const parts = imports\n        .split(',')\n        .map((s) => s.trim())\n        .filter(Boolean)\n      if (!parts.includes('_setMount')) parts.push('_setMount')\n      if (!parts.includes('_setSignal')) parts.push('_setSignal')\n      return `import { ${parts.join(', ')} } from '@aihu/runtime'`\n    },\n  )\n\n  // 4. Insert boot calls after the last `import` statement.\n  const lines = result.split('\\n')\n  let lastImportIdx = -1\n  for (let i = lines.length - 1; i >= 0; i--) {\n    const t = (lines[i] ?? '').trim()\n    if (t.startsWith('import ') || t.startsWith('import{')) {\n      lastImportIdx = i\n      break\n    }\n  }\n  if (lastImportIdx !== -1) {\n    lines.splice(lastImportIdx + 1, 0, '_setMount(mount)', '_setSignal(signal)', '')\n    result = lines.join('\\n')\n  }\n\n  return result\n}\n\n/**\n * Vite plugin that compiles .aihu files to TypeScript during build and dev.\n *\n * Use `enforce: 'pre'` so the hook fires before Vite/Rollup's built-in\n * parsers attempt to process the raw .aihu content as JavaScript.\n *\n * @example\n * // vite.config.ts\n * import { aihuCompilerPlugin } from '@aihu/compiler'\n * export default { plugins: [aihuCompilerPlugin()] }\n *\n * **Known Limitation — Bun + Rollup4 ESM incompatibility (v0):**\n *\n * `bun vite build` fails in the `fixtures/vite-counter` fixture with two\n * cascading errors:\n *\n * 1. **Missing devDependency:** `vite` is declared only as an optional\n *    `peerDependency` in `packages/compiler/package.json`. Bun does not\n *    install optional peers automatically, so `bun vite build` exits\n *    immediately with `Cannot find package 'vite'`.\n *\n * 2. **Bun + Rollup4 bridge:** Even with Vite installed, Bun processes\n *    `vite.config.ts` through its own internal bundler before handing off\n *    to Rollup4. When `@aihu/compiler` is resolved from the workspace\n *    symlink (`dist/index.js`), Bun's ESM loader evaluates the module at\n *    config-load time. The subprocess call inside `transform()` depends on\n *    the Rust binary being at `../bin/aihu-compile` relative to `dist/`\n *    (written by the postinstall hook). In a dev workspace where postinstall\n *    has not run, this path does not exist and `execFileSync` throws. Bun surfaces\n *    the error as a config-load failure, not a per-file transform error,\n *    causing the entire build to abort before any `.aihu` file is\n *    processed.\n *\n * **Workaround (v0):** Use `bun run integrate.ts` directly from\n * `packages/compiler/fixtures/vite-counter/`. This script calls\n * `transform()` from `@aihu/compiler` without involving Vite or Rollup.\n * Preconditions: (1) `cargo build --release` in `packages/compiler/`,\n * (2) `bun install` at the repo root.\n *\n * **v1 resolution:** Add `vite` as a `devDependency` in\n * `packages/compiler/package.json`; add a WASM or pre-built binary\n * strategy so the Rust binary is bundled with the npm package and does not\n * require a separate `cargo build --release` step.\n */\nexport function aihuCompilerPlugin(options?: AihuCompilerPluginOptions): VitePlugin {\n  const islandsEnabled = options?.islands !== false\n  const shadowMode = options?.shadowMode\n  return {\n    name: 'aihu-compiler',\n    enforce: 'pre',\n    transform(code, id) {\n      // Strip Vite query strings (e.g. `?import`, `?t=...`) before checking the extension.\n      const rawId = id.split('?')[0]!\n      if (!rawId.endsWith('.aihu')) return\n      return (async () => {\n        const result = transform(code, rawId)\n        const compiled =\n          shadowMode != null ? _injectShadowMode(result.code, shadowMode) : result.code\n        const elementTag = _extractElementTag(compiled)\n\n        let out: string\n\n        // Plan 3.3 — static-island fast path. Bypasses HMR injection because\n        // a component with no signals has no setup state to hot-replace.\n        // Static islands strip @aihu/runtime entirely — do NOT inject auto-wiring\n        // (it would reference _setMount/_setSignal as undefined identifiers).\n        if (islandsEnabled && elementTag !== null && _classifyIsland(compiled) === 'static') {\n          out = _buildStaticIsland(compiled, elementTag)\n        } else if (elementTag !== null) {\n          // Inject HMR instrumentation. The injected block is gated on\n          // `typeof __DEV__ !== 'undefined' && __DEV__` so production\n          // bundlers dead-code-eliminate it when they set __DEV__ = false.\n          out = _buildHmrCode(compiled, elementTag)\n          // Plan 3.3 — interactive islands also gain `defer` attribute\n          // support so individual instances can opt into lazy hydration.\n          out = _buildDeferredHydration(out, elementTag)\n          // Inject auto-wiring so consumers don't need a manual main.ts bootstrap.\n          out = _injectAutoWiring(out)\n        } else {\n          out = compiled\n          // Inject auto-wiring so consumers don't need a manual main.ts bootstrap.\n          out = _injectAutoWiring(out)\n        }\n\n        // The Rust compiler emits TypeScript (type casts, import type, etc.) and\n        // the injected HMR / defer helpers also contain TS generics and casts.\n        // Vite does NOT re-run its esbuild TypeScript-strip step when a plugin\n        // returns code for a non-.ts ID — so we strip types here ourselves using\n        // Vite's own transformWithEsbuild API (always available in a Vite context).\n        try {\n          const { transformWithEsbuild } = await import('vite')\n          const stripped = await transformWithEsbuild(out, 'component.ts', {\n            target: 'esnext',\n            sourcemap: false,\n          })\n          return { code: stripped.code, map: null }\n        } catch {\n          // If running outside Vite (e.g. tests, standalone transform), return as-is.\n          return { code: out, map: null }\n        }\n      })()\n    },\n  }\n}\n"],"mappings":"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"}

package/js/postinstall.ts

@@ -0,0 +1,354 @@
+/**
+ * Postinstall hook for @aihu/compiler.
+ *
+ * Resolution order (first match wins):
+ *
+ *   1. SCRIBE_SKIP_POSTINSTALL=1     → no-op, exit 0.
+ *   2. Binary already present at     → no-op, exit 0.
+ *      bin/aihu-compile<ext> OR
+ *      target/release/aihu-compile<ext>
+ *   3. SCRIBE_COMPILE_BIN=<path>     → copy that path → bin/, exit 0.
+ *   4. GitHub Releases download      → bin/aihu-compile<ext>, verify SHA256,
+ *                                       exit 0. (arch-4 §4.3 — sidecar
+ *                                       verification implemented v1.1.)
+ *   5. Local `cargo build --release` → target/release/aihu-compile<ext>,
+ *                                       exit 0.
+ *   6. Everything failed             → log warning, exit 0 anyway. The user
+ *                                       will need to either provide
+ *                                       SCRIBE_COMPILE_BIN or run
+ *                                       `cargo build --release` themselves
+ *                                       before invoking the compiler.
+ *
+ * The hard rule: this script MUST exit 0 in every "no binary acquired"
+ * branch. A non-zero exit aborts `bun install`, which prevents workspace
+ * symlinks from being created and breaks every downstream package that
+ * imports a `@aihu/*` sibling. Compile-time failure (when the user
+ * actually invokes the compiler without a binary) is acceptable and
+ * recoverable; install-time failure is not.
+ *
+ * Hard-fail exit 1 is reserved for these cases:
+ *   - SCRIBE_COMPILE_BIN is set but points at a missing file (user error,
+ *     surface immediately rather than silently swallow).
+ *   - SHA256 verification of a downloaded binary fails (integrity violation —
+ *     do NOT run a tampered binary).
+ *   - Catastrophic unexpected exception (programming error in this script).
+ *
+ * Local dev override: if SCRIBE_COMPILE_BIN env var is set, that path is
+ * used instead of downloading. This lets contributors who built from
+ * source via `cargo build --release` point the compiler at their build.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+interface AssetMapping {
+  asset: string
+  ext: '' | '.exe'
+}
+
+function resolveAsset(platform: NodeJS.Platform, arch: string): AssetMapping | null {
+  if (platform === 'darwin' && arch === 'arm64') {
+    return { asset: 'aihu-compile-darwin-arm64', ext: '' }
+  }
+  if (platform === 'darwin' && arch === 'x64') {
+    return { asset: 'aihu-compile-darwin-x64', ext: '' }
+  }
+  if (platform === 'linux' && arch === 'x64') {
+    return { asset: 'aihu-compile-linux-x64', ext: '' }
+  }
+  // arch-4 §4.2 — aarch64-linux added in v1.1 release matrix.
+  if (platform === 'linux' && arch === 'arm64') {
+    return { asset: 'aihu-compile-linux-arm64', ext: '' }
+  }
+  if (platform === 'win32' && arch === 'x64') {
+    return { asset: 'aihu-compile-windows-x64.exe', ext: '.exe' }
+  }
+  return null
+}
+
+const TAG = '[@aihu/compiler postinstall]'
+
+function info(msg: string): void {
+  process.stdout.write(`${TAG} ${msg}\n`)
+}
+
+function warn(msg: string): void {
+  process.stderr.write(`${TAG} WARN: ${msg}\n`)
+}
+
+function hardFail(msg: string): never {
+  process.stderr.write(`${TAG} ERROR: ${msg}\n`)
+  process.exit(1)
+}
+
+function softExit(msg: string): never {
+  warn(msg)
+  warn(
+    'bun install will continue. To enable the compiler later, set ' +
+      'SCRIBE_COMPILE_BIN to a built binary path or run ' +
+      '`cargo build --release` from packages/compiler/ when a Rust ' +
+      'toolchain is available.',
+  )
+  process.exit(0)
+}
+
+interface DownloadResult {
+  ok: boolean
+  reason?: string
+  status?: number
+}
+
+async function tryDownload(url: string, dest: string): Promise<DownloadResult> {
+  let response: Response
+  try {
+    response = await fetch(url, { redirect: 'follow' })
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason: `network error: ${detail}` }
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: `HTTP ${response.status} ${response.statusText}`,
+      status: response.status,
+    }
+  }
+  let buf: Buffer
+  try {
+    buf = Buffer.from(await response.arrayBuffer())
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason: `body read failed: ${detail}` }
+  }
+  if (buf.length === 0) {
+    return { ok: false, reason: 'response body was empty' }
+  }
+  try {
+    writeFileSync(dest, buf)
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason: `write failed: ${detail}` }
+  }
+  return { ok: true }
+}
+
+/**
+ * Verify a downloaded binary's SHA256 digest against the matching `.sha256`
+ * sidecar from GitHub Releases (arch-4 §4.3).
+ *
+ * Returns true on match, false on any failure (network, mismatch, parse).
+ * The caller decides whether to fail hard or fall through; for download path
+ * a mismatch is hardFail (integrity violation), other reasons soft-warn.
+ */
+async function verifySha256(
+  binaryPath: string,
+  sidecarUrl: string,
+): Promise<{ ok: boolean; reason?: string; expected?: string; actual?: string }> {
+  let response: Response
+  try {
+    response = await fetch(sidecarUrl, { redirect: 'follow' })
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason: `sidecar network error: ${detail}` }
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: `sidecar HTTP ${response.status} ${response.statusText}`,
+    }
+  }
+  const sidecarText = (await response.text()).trim()
+  // Sidecar format: hex digest (lowercase, 64 chars). Some tools prepend a filename;
+  // accept either `<hash>` or `<hash>  <name>` and extract the first whitespace-delimited token.
+  const expected = sidecarText.split(/\s+/)[0]?.toLowerCase()
+  if (!expected || !/^[0-9a-f]{64}$/i.test(expected)) {
+    return {
+      ok: false,
+      reason: `malformed sidecar (expected 64-char hex, got "${sidecarText.slice(0, 80)}")`,
+    }
+  }
+
+  let actual: string
+  try {
+    const fileBuf = readFileSync(binaryPath)
+    actual = createHash('sha256').update(fileBuf).digest('hex')
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, reason: `local hash failed: ${detail}` }
+  }
+
+  if (actual !== expected) {
+    return { ok: false, reason: 'digest mismatch', expected, actual }
+  }
+  return { ok: true }
+}
+
+function tryLocalBuild(pkgDir: string): boolean {
+  // Check for cargo first — quick probe without spawning a build.
+  const probe = spawnSync('cargo', ['--version'], {
+    stdio: 'ignore',
+    shell: false,
+  })
+  if (probe.error || probe.status !== 0) {
+    info('cargo not available; skipping local Rust build fallback.')
+    return false
+  }
+  info('attempting local `cargo build --release` (Rust toolchain detected)…')
+  const build = spawnSync('cargo', ['build', '--release'], {
+    cwd: pkgDir,
+    stdio: 'inherit',
+    shell: false,
+  })
+  if (build.error || build.status !== 0) {
+    warn(
+      `local cargo build failed (status=${build.status ?? 'unknown'}). The compiler binary was not built.`,
+    )
+    return false
+  }
+  info('local cargo build succeeded.')
+  return true
+}
+
+async function main(): Promise<void> {
+  if (process.env.SCRIBE_SKIP_POSTINSTALL) {
+    info('SCRIBE_SKIP_POSTINSTALL set; skipping all binary-acquisition steps.')
+    return
+  }
+
+  const platform = process.platform
+  const arch = process.arch
+
+  const mapping = resolveAsset(platform, arch)
+  if (!mapping) {
+    softExit(
+      `unsupported platform: ${platform}/${arch} ` +
+        '(supported: darwin/arm64, darwin/x64, linux/x64, linux/arm64, win32/x64).',
+    )
+  }
+
+  const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+  const binDir = resolve(pkgDir, 'bin')
+  const binPath = resolve(binDir, `aihu-compile${mapping.ext}`)
+  const targetReleaseBin = resolve(pkgDir, 'target', 'release', `aihu-compile${mapping.ext}`)
+
+  // Ensure target directory exists before any write operations.
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true })
+  }
+
+  // Idempotency: nothing to do if a binary is already in place at either
+  // the released-asset path (bin/) or the local-build path (target/release).
+  if (existsSync(binPath)) {
+    info(`bin already present at ${binPath}, skipping.`)
+    return
+  }
+  if (existsSync(targetReleaseBin)) {
+    info(`local cargo build already present at ${targetReleaseBin}, skipping.`)
+    return
+  }
+
+  // Local dev override — copy a locally built binary instead of downloading.
+  const override = process.env.SCRIBE_COMPILE_BIN
+  if (override) {
+    if (!existsSync(override)) {
+      // User explicitly pointed at a path that doesn't exist — fail loudly.
+      hardFail(`SCRIBE_COMPILE_BIN points to ${override} but that file does not exist.`)
+    }
+    copyFileSync(override, binPath)
+    if (platform !== 'win32') {
+      chmodSync(binPath, 0o755)
+    }
+    info(`copied ${override} -> ${binPath} (SCRIBE_COMPILE_BIN override).`)
+    return
+  }
+
+  // Strategy A — try the GitHub Releases `latest/download` redirect.
+  // On any failure (404 because no release exists yet, network unavailable,
+  // empty response, write failure), fall through to Strategy B without
+  // aborting the install.
+  const baseUrl = `https://github.com/fellwork/aihu/releases/latest/download/${mapping.asset}`
+  const sidecarUrl = `${baseUrl}.sha256`
+  info(`fetching ${baseUrl}`)
+  const downloaded = await tryDownload(baseUrl, binPath)
+  if (downloaded.ok) {
+    // Verify SHA256 against sidecar before trusting the binary (arch-4 §4.3).
+    info(`verifying SHA256 against ${sidecarUrl}`)
+    const verified = await verifySha256(binPath, sidecarUrl)
+    if (verified.ok) {
+      if (platform !== 'win32') {
+        chmodSync(binPath, 0o755)
+      }
+      info(`installed binary at ${binPath} (SHA256 verified).`)
+      return
+    }
+    if (verified.reason === 'digest mismatch') {
+      // Integrity violation — DO NOT leave the bad binary on disk.
+      try {
+        unlinkSync(binPath)
+      } catch {
+        /* swallow — the next strategy will overwrite */
+      }
+      hardFail(
+        `binary hash verification failed for ${mapping.asset}.\n` +
+          `  expected: ${verified.expected ?? '(unknown)'}\n` +
+          `  actual:   ${verified.actual ?? '(unknown)'}\n` +
+          'Refusing to install a tampered binary. Re-run after the release ' +
+          'workflow republishes the asset, or set SCRIBE_COMPILE_BIN to a trusted local build.',
+      )
+    }
+    // Sidecar fetch/parse failures: warn but don't hard-fail (the binary itself downloaded).
+    // This lets pre-v1.1 releases (no sidecars) continue to install.
+    warn(`SHA256 verification skipped: ${verified.reason}.`)
+    if (platform !== 'win32') {
+      chmodSync(binPath, 0o755)
+    }
+    info(`installed binary at ${binPath} (UNVERIFIED — sidecar unavailable).`)
+    return
+  }
+
+  // 404 on aarch64-linux pre-v1.1 release publish — graceful fallthrough.
+  if (downloaded.status === 404 && platform === 'linux' && arch === 'arm64') {
+    info(
+      'aarch64-linux binary not yet published for this release; falling through to source build.',
+    )
+  } else {
+    warn(`release-binary download from ${baseUrl} failed: ${downloaded.reason}.`)
+  }
+
+  // Strategy B — attempt a local Rust build. The Rust crate lives at
+  // packages/compiler/Cargo.toml; `cargo build --release` produces the
+  // binary at packages/compiler/target/release/aihu-compile<ext>, which
+  // is where js/index.ts looks via SCRIBE_COMPILE_BIN ?? '../target/release/...'.
+  if (tryLocalBuild(pkgDir)) {
+    if (existsSync(targetReleaseBin)) {
+      info(`compiler binary built locally at ${targetReleaseBin}.`)
+      return
+    }
+    warn(`cargo build reported success but ${targetReleaseBin} is missing; falling through.`)
+  }
+
+  // Strategy C — give up, but DO NOT fail the install. The compiler may be
+  // unused in this workspace (e.g. consumers only depend on @aihu/runtime
+  // and @aihu/signals). Compile-time invocation will surface a clear
+  // error if/when the user actually tries to compile a .aihu file.
+  softExit(
+    'no compiler binary available after release-download and local-build fallbacks. ' +
+      'This is fine if you do not need to compile .aihu files in this workspace.',
+  )
+}
+
+main().catch((err: unknown) => {
+  const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
+  hardFail(`Unexpected failure: ${detail}`)
+})

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aihu/compiler",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "aihu-compile": "./bin/aihu-compile"
+  },
+  "files": [
+    "dist",
+    "js/postinstall.ts",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rolldown -c",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "bun run js/postinstall.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "description": "Single File Component (.aihu) compiler — Rust binary + JS glue.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fellwork/aihu.git",
+    "directory": "packages/compiler"
+  },
+  "homepage": "https://github.com/fellwork/aihu/tree/main/packages/compiler#readme",
+  "bugs": "https://github.com/fellwork/aihu/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}