broapp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Praveen Vijayan
+
+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,46 @@
+# broapp
+
+Runtime and build tooling for local applications made of a Bun host, a browser
+UI, and a [Brobridge](https://github.com/praveenvijayan/brobridge) connection
+between them.
+
+You normally get this as a dependency of a generated project:
+
+```bash
+bun create broapp my-app
+```
+
+Full documentation lives in the
+[repository](https://github.com/praveenvijayan/broapp).
+
+## Entry points
+
+| Import | What it holds |
+| --- | --- |
+| `broapp/shared` | The contract, schemas, error types. Safe for both sides. |
+| `broapp/host` | `createHostApp`, `startApp`, the data directory, the browser launcher. |
+| `broapp/client` | The framework-agnostic browser client. |
+| `broapp/react` | `BroappProvider`, `useOperation`, `useStream`, `useConnection`. |
+| `broapp/build` | `buildPage`, `buildBinary`, `defineConfig`. |
+
+Never import `broapp/host` from browser code: it pulls in `node:fs` and
+`Bun.spawn`, and a browser bundle that reaches it fails the build — which is the
+intended outcome.
+
+## The command
+
+```
+broapp dev [--no-open]        Watch, rebuild, restart the host
+broapp build [--target <id>]  Build the UI and compile an executable
+broapp build --page           Build the UI document only
+broapp build --all-targets    Every supported target
+```
+
+## Requirements
+
+Bun 1.2 or newer. Peer dependency on React 18 or newer, and only if you use
+`broapp/react`.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "broapp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Build tooling and runtime for local applications made of a Bun host, a browser UI, and a Brobridge connection between them",
+  "license": "MIT",
+  "homepage": "https://github.com/praveenvijayan/broapp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praveenvijayan/broapp.git",
+    "directory": "packages/broapp"
+  },
+  "bugs": {
+    "url": "https://github.com/praveenvijayan/broapp/issues"
+  },
+  "keywords": [
+    "bun",
+    "brobridge",
+    "local-first",
+    "desktop",
+    "browser-ui",
+    "single-file-executable"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "broapp": "src/cli/main.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/shared/index.ts",
+    "./shared": "./src/shared/index.ts",
+    "./host": "./src/host/index.ts",
+    "./client": "./src/client/index.ts",
+    "./react": "./src/react/index.ts",
+    "./build": "./src/cli/index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@brobridgejs/client": "^0.2.1",
+    "@brobridgejs/core": "^0.2.1",
+    "brobridge": "^0.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0"
+  }
+}

package/src/cli/build-binary.ts

@@ -0,0 +1,98 @@
+/**
+ * Compiling the host into a single-file executable.
+ *
+ * `bun build --compile` bundles the host entry point together with the Bun
+ * runtime. The UI arrives through an ordinary import of the built HTML
+ * document with `{ type: "text" }`, which Bun inlines into the bundle — so
+ * there is no asset directory to ship, nothing to resolve at runtime relative
+ * to the executable, and nothing to break when the binary is moved.
+ */
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import type { Target } from './targets.ts';
+import { currentTarget, findTarget, TARGETS } from './targets.ts';
+
+/** Options for {@link buildBinary}. */
+export interface BuildBinaryOptions {
+  /** Host entry point, e.g. `src/host/main.ts`. */
+  readonly entry: string;
+  /** Executable base name; the target suffix and `.exe` are added. */
+  readonly name: string;
+  /** Output directory. Default `release`. */
+  readonly outDir?: string;
+  /** Target ids. Default: the current platform only. */
+  readonly targets?: readonly string[];
+  /** Project root. Default `process.cwd()`. */
+  readonly root?: string;
+  /** Default `true`. */
+  readonly minify?: boolean;
+  /**
+   * Compile to bytecode. Default `true`.
+   *
+   * It cuts startup time noticeably and costs binary size. Turn it off if a
+   * dependency misbehaves under it.
+   */
+  readonly bytecode?: boolean;
+  /** Append the target id to the filename. Default `true` for multi-target builds. */
+  readonly suffixTarget?: boolean;
+}
+
+/** One produced executable. */
+export interface BuiltBinary {
+  readonly target: Target;
+  readonly path: string;
+  readonly bytes: number;
+  /** True when this binary can run on the machine that built it. */
+  readonly native: boolean;
+}
+
+/** Compile one executable per requested target. */
+export async function buildBinary(options: BuildBinaryOptions): Promise<BuiltBinary[]> {
+  const root = options.root ?? process.cwd();
+  const outDir = resolve(root, options.outDir ?? 'release');
+  const entry = resolve(root, options.entry);
+  const native = currentTarget();
+
+  const requested = options.targets ?? [native.id];
+  const targets = requested.map((id) => {
+    const target = findTarget(id);
+    if (target === undefined) {
+      throw new Error(`unknown target ${JSON.stringify(id)}. Supported: ${TARGETS.map((t) => t.id).join(', ')}`);
+    }
+    return target;
+  });
+
+  const suffix = options.suffixTarget ?? targets.length > 1;
+  await mkdir(outDir, { recursive: true });
+
+  const built: BuiltBinary[] = [];
+  for (const target of targets) {
+    const filename = `${options.name}${suffix ? `-${target.id}` : ''}${target.ext}`;
+    const outFile = join(outDir, filename);
+    await mkdir(dirname(outFile), { recursive: true });
+
+    const argv = [
+      'bun',
+      'build',
+      '--compile',
+      `--target=bun-${target.id}`,
+      ...(options.minify === false ? [] : ['--minify']),
+      ...(options.bytecode === false ? [] : ['--bytecode']),
+      entry,
+      '--outfile',
+      outFile,
+    ];
+    const child = Bun.spawn(argv, { cwd: root, stdout: 'inherit', stderr: 'inherit' });
+    if ((await child.exited) !== 0) {
+      throw new Error(`compilation failed for ${target.id}`);
+    }
+    built.push({
+      target,
+      path: outFile,
+      bytes: (await stat(outFile)).size,
+      native: target.id === native.id,
+    });
+  }
+  return built;
+}

package/src/cli/build-page.ts

@@ -0,0 +1,222 @@
+/**
+ * Bundling the browser UI into one self-contained HTML document.
+ *
+ * Brobridge's route table is exactly `/`, `/ws` and `/rpc` — there is no
+ * static file route, by design, so nothing about the bridge ever touches the
+ * filesystem in response to a request. That constraint decides the whole
+ * packaging story: the UI must be *one document*, with its CSS and JavaScript
+ * inline, because a `<script src="/assets/app.js">` would 404.
+ *
+ * That turns out to suit a compiled single-file application well. One document
+ * is one `import … with { type: "text" }`, which Bun embeds in the executable,
+ * and there is no asset manifest to keep in step.
+ *
+ * Two properties are enforced here rather than trusted:
+ *
+ * 1. No off-origin references. A local application that pulls a font or a
+ *    script from a CDN stops working offline and hands a third party a view of
+ *    when the user runs it. The check is a scan of the built document.
+ * 2. A restrictive `Content-Security-Policy`, with the inline script pinned by
+ *    SHA-256 hash rather than allowed by `'unsafe-inline'`. The hash is
+ *    computed from the actual bundle, so it cannot drift. Brobridge sets no
+ *    CSP of its own (it sets `Referrer-Policy`, `Cache-Control: no-store` and
+ *    `X-Content-Type-Options`), and it only lets a host application supply a
+ *    body, so the policy travels in a `<meta http-equiv>`.
+ */
+import { createHash } from 'node:crypto';
+import { dirname, resolve } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+/** Options for {@link buildPage}. */
+export interface BuildPageOptions {
+  /** Browser entry point, e.g. `src/ui/main.tsx`. */
+  readonly entry: string;
+  /** HTML shell containing `<!--BROAPP_HEAD-->` and `<!--BROAPP_BODY-->`. */
+  readonly template: string;
+  /** Where to write the document. */
+  readonly outFile: string;
+  /** Default `true`. Off makes a development bundle readable in devtools. */
+  readonly minify?: boolean;
+  /** Project root the entry and template are resolved against. Default `process.cwd()`. */
+  readonly root?: string;
+  /**
+   * Extra CSP sources, merged into the generated policy.
+   *
+   * `connect-src` already covers the bridge's own origin over `http:` and
+   * `ws:`. Adding a remote origin here defeats the offline guarantee, so the
+   * off-origin scan still runs.
+   */
+  readonly csp?: Readonly<Record<string, readonly string[]>>;
+}
+
+/** What {@link buildPage} produced. */
+export interface BuildPageResult {
+  readonly outFile: string;
+  readonly bytes: number;
+  readonly scriptHash: string;
+}
+
+/**
+ * The base policy.
+ *
+ * `default-src 'none'` means every directive not listed below is denied, so a
+ * directive nobody thought about fails closed. `connect-src` allows the page's
+ * own origin plus `ws:`/`wss:` — the WebSocket URL has a different scheme from
+ * the document's, and `'self'` does not cover it in any current browser.
+ */
+function policy(scriptHash: string, styleHash: string | null, extra: BuildPageOptions['csp']): string {
+  const directives: Record<string, string[]> = {
+    'default-src': ["'none'"],
+    'script-src': [`'sha256-${scriptHash}'`],
+    // A hash of the empty string is not a policy — it declares that a
+    // stylesheet which is not there is permitted. With no CSS, say `'none'`.
+    'style-src': styleHash === null ? ["'none'"] : [`'sha256-${styleHash}'`],
+    'img-src': ["'self'", 'data:'],
+    'font-src': ["'self'", 'data:'],
+    // The bridge's WebSocket URL has a `ws:` scheme while the document has
+    // `http:`. CSP Level 3 says `'self'` covers that upgrade, but not every
+    // engine implements it, so the one host the bridge can bind is named
+    // explicitly. The port is ephemeral and unknowable at build time, hence
+    // `:*`.
+    //
+    // Only `127.0.0.1`. Broapp does not forward Brobridge's `host` option, so
+    // the authority is always that — and Brobridge's trust fence refuses any
+    // request whose `Host` header names something else. Listing `localhost` or
+    // `[::1]` would widen the policy to cover origins the application can
+    // never actually be served from.
+    'connect-src': ["'self'", 'ws://127.0.0.1:*'],
+    'base-uri': ["'none'"],
+    'form-action': ["'none'"],
+    // No `frame-ancestors`. It is one of the three directives the CSP
+    // specification requires user agents to *ignore* in a `<meta>` element
+    // (with `report-uri` and `sandbox`), and a meta element is the only way a
+    // host application can express a policy — Brobridge sets the response
+    // headers and offers no hook for adding one. Declaring it here would put
+    // an inert directive in the document and invite the reader to count it as
+    // protection.
+    //
+    // Framing is refused anyway, one layer down: Brobridge's trust fence
+    // allows only `Sec-Fetch-Site: same-origin` or `none`, so a page on
+    // another origin that frames the application gets a 403 rather than a
+    // rendered frame. See docs/security.md.
+    'object-src': ["'none'"],
+  };
+  for (const [directive, sources] of Object.entries(extra ?? {})) {
+    directives[directive] = [...(directives[directive] ?? []), ...sources];
+  }
+  return Object.entries(directives)
+    .map(([directive, sources]) => `${directive} ${sources.join(' ')}`)
+    .join('; ');
+}
+
+function sha256(input: string): string {
+  return createHash('sha256').update(input, 'utf8').digest('base64');
+}
+
+/**
+ * A `</script` inside string data would end the inline script element early —
+ * the HTML tokenizer does not know it is inside a JavaScript string. The same
+ * goes for a comment opener.
+ */
+function escapeForInlineScript(code: string): string {
+  return code.replaceAll('</script', String.raw`<\/script`).replaceAll('<!--', String.raw`<\!--`);
+}
+
+/**
+ * Positions in a document that actually cause a network fetch.
+ *
+ * A bare `"https://…"` inside JavaScript is a *string*, not a request — React's
+ * production build embeds `https://react.dev/errors/…` in its error messages,
+ * and rejecting that would reject React. What matters is a URL somewhere the
+ * browser will load from: an HTML attribute, a CSS `url()`, or an `@import`.
+ *
+ * The Content-Security-Policy is the real enforcement — `default-src 'none'`
+ * blocks every off-origin fetch at runtime whatever the source says. This scan
+ * exists so the failure happens at build time, where a developer can see it,
+ * rather than as an empty box in somebody's browser.
+ */
+const LOAD_POSITIONS: readonly RegExp[] = [
+  /\b(?:src|href|srcset|poster|data|action|formaction)\s*=\s*["']?(?:https?:)?\/\/[^"'\s>]+/gi,
+  /url\(\s*["']?(?:https?:)?\/\/[^"')]+/gi,
+  /@import\s+(?:url\()?\s*["'](?:https?:)?\/\/[^"']+/gi,
+];
+
+/** The first off-origin load position in `html`, or `null`. */
+function findOffOrigin(html: string): string | null {
+  for (const pattern of LOAD_POSITIONS) {
+    pattern.lastIndex = 0;
+    const match = pattern.exec(html);
+    if (match !== null) return match[0].slice(0, 160);
+  }
+  return null;
+}
+
+/** Build the single-document UI. */
+export async function buildPage(options: BuildPageOptions): Promise<BuildPageResult> {
+  const root = options.root ?? process.cwd();
+  const entry = resolve(root, options.entry);
+  const templatePath = resolve(root, options.template);
+  const outFile = resolve(root, options.outFile);
+
+  const built = await Bun.build({
+    entrypoints: [entry],
+    target: 'browser',
+    minify: options.minify !== false,
+    // Not `--splitting`: a second chunk would need a second HTTP route, and
+    // there is none.
+    splitting: false,
+    define: { 'process.env.NODE_ENV': JSON.stringify(options.minify === false ? 'development' : 'production') },
+  });
+  if (!built.success) {
+    throw new Error(`UI bundle failed:\n${built.logs.map(String).join('\n')}`);
+  }
+
+  const chunks = built.outputs.filter((output) => output.kind === 'entry-point' || output.kind === 'chunk');
+  if (chunks.length !== 1) {
+    throw new Error(
+      `expected exactly one JavaScript chunk, got ${String(chunks.length)}. A dynamic import would need a second HTTP route, and the bridge serves only "/".`,
+    );
+  }
+  const firstChunk = chunks[0];
+  if (firstChunk === undefined) throw new Error('UI bundle produced no output');
+  const script = await firstChunk.text();
+
+  const cssOutputs = built.outputs.filter((output) => output.path.endsWith('.css'));
+  let css = '';
+  for (const output of cssOutputs) css += await output.text();
+
+  const template = await Bun.file(templatePath).text();
+  if (!template.includes('<!--BROAPP_HEAD-->') || !template.includes('<!--BROAPP_BODY-->')) {
+    throw new Error(`${templatePath} must contain <!--BROAPP_HEAD--> and <!--BROAPP_BODY--> markers`);
+  }
+
+  const styleTag = css === '' ? '' : `<style>${css}</style>`;
+  // Hash the script *as the browser will see it*: the escaping below changes
+  // the bytes, so hashing before it would produce a policy that blocks the
+  // very script it was computed from.
+  const scriptBody = escapeForInlineScript(script);
+  const head =
+    `<meta http-equiv="Content-Security-Policy" content="${policy(sha256(scriptBody), css === '' ? null : sha256(css), options.csp)}">` +
+    styleTag;
+  const finalHtml = template
+    .replace('<!--BROAPP_HEAD-->', () => head)
+    .replace('<!--BROAPP_BODY-->', () => `<script type="module">${scriptBody}</script>`);
+
+  // The policy element itself names schemes and hosts; exclude it from the scan.
+  const withoutPolicy = finalHtml.replace(/<meta http-equiv="Content-Security-Policy"[^>]*>/g, '');
+  const offOrigin = findOffOrigin(withoutPolicy);
+  if (offOrigin !== null) {
+    throw new Error(
+      `the built page loads from an off-origin URL, which would break offline operation and leak when the application runs:\n  ${offOrigin}\nInline or embed the asset instead.`,
+    );
+  }
+
+  await mkdir(dirname(outFile), { recursive: true });
+  await Bun.write(outFile, finalHtml);
+
+  return {
+    outFile,
+    bytes: new TextEncoder().encode(finalHtml).byteLength,
+    scriptHash: sha256(scriptBody),
+  };
+}

package/src/cli/config.ts

@@ -0,0 +1,77 @@
+/**
+ * Project configuration.
+ *
+ * One optional file, `broapp.config.ts`, with sensible defaults for every
+ * field — so a generated project has a config that is mostly there to be read
+ * rather than edited.
+ */
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/** What `broapp.config.ts` may set. */
+export interface BroappConfig {
+  /** Browser entry point. Default `src/ui/main.tsx`. */
+  readonly uiEntry?: string;
+  /** HTML shell. Default `src/ui/index.html`. */
+  readonly uiTemplate?: string;
+  /** Host entry point. Default `src/host/main.ts`. */
+  readonly hostEntry?: string;
+  /** Where the built page goes. Must match what the host imports. Default `dist/ui.html`. */
+  readonly pageOut?: string;
+  /** Executable base name. Default: the package name. */
+  readonly binaryName?: string;
+  /** Output directory for executables. Default `release`. */
+  readonly outDir?: string;
+  /** Extra Content-Security-Policy sources. */
+  readonly csp?: Readonly<Record<string, readonly string[]>>;
+  /** Compile to bytecode. Default `true`. */
+  readonly bytecode?: boolean;
+}
+
+/** A config with every default applied. */
+export interface ResolvedConfig extends Required<Omit<BroappConfig, 'csp'>> {
+  readonly csp: Readonly<Record<string, readonly string[]>>;
+  readonly root: string;
+}
+
+const CONFIG_FILES = ['broapp.config.ts', 'broapp.config.js', 'broapp.config.mjs'];
+
+/** Read and resolve the project's configuration. */
+export async function loadConfig(root: string = process.cwd()): Promise<ResolvedConfig> {
+  let user: BroappConfig = {};
+  for (const candidate of CONFIG_FILES) {
+    const path = resolve(root, candidate);
+    if (!existsSync(path)) continue;
+    const module = (await import(path)) as { default?: BroappConfig };
+    user = module.default ?? {};
+    break;
+  }
+
+  let packageName = 'app';
+  const packageJson = resolve(root, 'package.json');
+  if (existsSync(packageJson)) {
+    const parsed = (await Bun.file(packageJson).json()) as { name?: string };
+    if (typeof parsed.name === 'string' && parsed.name !== '') {
+      // A scoped name is not a legal filename on Windows and is awkward
+      // everywhere else, so the scope is dropped for the executable.
+      packageName = parsed.name.replace(/^@[^/]+\//, '');
+    }
+  }
+
+  return {
+    root,
+    uiEntry: user.uiEntry ?? 'src/ui/main.tsx',
+    uiTemplate: user.uiTemplate ?? 'src/ui/index.html',
+    hostEntry: user.hostEntry ?? 'src/host/main.ts',
+    pageOut: user.pageOut ?? 'dist/ui.html',
+    binaryName: user.binaryName ?? packageName,
+    outDir: user.outDir ?? 'release',
+    bytecode: user.bytecode ?? true,
+    csp: user.csp ?? {},
+  };
+}
+
+/** Type helper, so `broapp.config.ts` gets completion. */
+export function defineConfig(config: BroappConfig): BroappConfig {
+  return config;
+}