feat: staging_srcs on ts_bundle + working Remix example

Add staging_srcs attr to ts_bundle that copies source files to a writable
staging directory before running Vite. This lets framework Vite plugins
(Remix, TanStack Start) scan source files for route discovery and write
codegen outputs, while the actual bundle still uses pre-compiled .js from oxc.

The staging dir becomes the Vite root automatically when staging_srcs is set.
No framework-specific code in rules_typescript — one general mechanism.

New: examples/remix-app/ with @remix-run/dev Vite plugin producing a real
Remix SPA bundle with route-based code splitting (8 chunks, hashed filenames,
Vite manifest).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mikn

examples/remix-app/.bazelversion

@@ -0,0 +1 @@
+9.0.0

examples/remix-app/BUILD.bazel

@@ -0,0 +1,211 @@
+"""Root BUILD file for the examples/remix-app workspace.
+
+Demonstrates:
+  - Remix v2 SPA mode with rules_typescript
+  - staging_srcs: copies app/ route files into a writable staging dir so
+    the Remix vitePlugin can scan routes and write codegen
+  - vite_config: injects the Remix Vite plugin while preserving Bazel
+    resolve.alias and outDir integration
+  - How framework plugins interact with the Bazel sandbox
+
+Run `bazel run //:gazelle` to regenerate BUILD files.
+Run `bazel build //...` to compile all packages.
+Run `bazel build //:app_plain` to produce a plain Vite SPA bundle (no Remix).
+Run `bazel build //:app_remix` to produce a full Remix SPA bundle with routes.
+
+── What :app_remix does ───────────────────────────────────────────────────────
+
+:app_remix uses ts_bundle in app mode with:
+  - staging_srcs = glob(["app/**/*.tsx"]) + ["package.json", "index.html"]
+    Copies all app/ source files plus required project files into a writable
+    _staging/ directory before Vite runs. VITE_STAGING_ROOT is set to the
+    staging dir so the Remix vitePlugin finds app/routes/*.tsx there.
+  - vite_config = "remix-vite.config.mjs"
+    Injects vitePlugin() from @remix-run/dev in SPA mode (ssr: false) and
+    sets buildDirectory = VITE_OUT_DIR so Remix writes its output into the
+    Bazel-declared directory (app_remix_bundle/).
+
+── Remix SPA mode ──────────────────────────────────────────────────────────────
+
+Remix v2 supports SPA mode (ssr: false) which:
+  - Produces only a client bundle (no server bundle).
+  - Does not require app/entry.server.tsx or a Node.js adapter.
+  - Outputs to buildDirectory/client/ (configurable via vitePlugin options).
+
+── How the integration works ───────────────────────────────────────────────────
+
+The three key pieces that make Remix work in the Bazel sandbox:
+
+  1. staging_srcs (writable source directory):
+     Remix's vitePlugin() must write codegen files (route types, manifests)
+     during the build. The Bazel source tree is read-only. staging_srcs copies
+     source files into a writable _staging/ dir inside the action sandbox.
+     VITE_STAGING_ROOT points to this dir; vite.root is set to it so Remix
+     finds app/routes/*.tsx there.
+
+  2. HTML in staging (fixes Rollup path traversal):
+     When staging is the Vite root, the HTML file must also be inside staging
+     (not at ../_html_staging/). The wrapper script detects when index.html
+     is staged and updates VITE_HTML_PATH to point to the staged copy,
+     so rollupOptions.input uses a clean relative path with no '..'.
+
+  3. buildDirectory = VITE_OUT_DIR (fixes output capture):
+     By default, Remix overrides Vite's build.outDir and writes to
+     "<viteRoot>/build/client/". Since viteRoot = staging dir, the output
+     would land outside the Bazel-declared directory. remix-vite.config.mjs
+     passes buildDirectory = process.env["VITE_OUT_DIR"] to the Remix plugin,
+     redirecting output into app_remix_bundle/client/ — inside the declared dir.
+
+── What does NOT work with full SSR Remix in Bazel ────────────────────────────
+
+Full SSR Remix (ssr: true, the default) requires:
+  1. A server entry (app/entry.server.tsx).
+  2. A separate server bundle build (outputs to buildDirectory/server/).
+  3. A Node.js adapter (@remix-run/node or @remix-run/express).
+
+The dual-output model (client + server) is architecturally incompatible with
+ts_bundle's single declared_directory output. Use SPA mode for Bazel-native
+Remix deployments.
+
+── Route compilation model ──────────────────────────────────────────────────────
+
+Note: Remix compiles route TypeScript via its own Vite transforms, not via
+Bazel's oxc compiler. The oxc-compiled .js files in bazel-bin are available
+via resolve.alias but Remix uses the staged .tsx files directly for routes.
+This is by design: staging makes source available; Remix handles compilation.
+The ts_compile targets (entry_client, root, routes) are still useful for
+incremental compilation validation and can be depended on by other targets.
+"""
+
+load("@gazelle//:def.bzl", "gazelle")
+load("@rules_typescript//npm:defs.bzl", "node_modules")
+load("@rules_typescript//ts:defs.bzl", "ts_bundle", "ts_compile")
+load("@rules_typescript//vite:bundler.bzl", "vite_bundler")
+
+# Run "bazel run //:gazelle" to auto-generate BUILD files.
+gazelle(
+    name = "gazelle",
+    gazelle = "@rules_typescript//gazelle:gazelle_ts",
+)
+
+# ── Compilation targets ──────────────────────────────────────────────────────
+#
+# Each ts_compile target covers files in a single directory. This is required
+# by rules_typescript's oxc invocation: when multiple files are compiled
+# together, they must share the same strip-dir-prefix (their common directory).
+# Files in different subdirectories (app/ vs app/routes/) must be in separate
+# targets.
+#
+# The staging_srcs on ts_bundle accepts any label_list, so we can pass all
+# source files to glob the full app/ tree — the wrapper stages each file at
+# its package-relative path.
+
+# Compile the Remix client entry point (single-file target — required by
+# ts_bundle which expects exactly 1 .js output from the entry_point).
+ts_compile(
+    name = "entry_client",
+    srcs = ["app/entry.client.tsx"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "@npm//:react",
+        "@npm//:react-dom",
+        "@npm//:remix-run_react",
+    ],
+)
+
+# Compile the root component (single-file).
+ts_compile(
+    name = "root",
+    srcs = ["app/root.tsx"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "@npm//:react",
+        "@npm//:remix-run_react",
+    ],
+)
+
+# Compile the route components (all in app/routes/).
+ts_compile(
+    name = "routes",
+    srcs = [
+        "app/routes/_index.tsx",
+        "app/routes/about.tsx",
+    ],
+    visibility = ["//visibility:public"],
+    deps = [
+        "@npm//:react",
+        "@npm//:remix-run_react",
+    ],
+)
+
+# node_modules tree with vite, remix, and their transitive deps.
+node_modules(
+    name = "node_modules",
+    deps = [
+        "@npm//:vite",
+        "@npm//:react",
+        "@npm//:react-dom",
+        "@npm//:remix-run_dev",
+        "@npm//:remix-run_react",
+        "@npm//:remix-run_node",
+    ],
+)
+
+# Vite bundler instance.
+vite_bundler(
+    name = "vite",
+    vite = "@npm//:vite",
+    node_modules = ":node_modules",
+)
+
+# ── Plain SPA bundle (no Remix plugin) ──────────────────────────────────────
+# This always works: plain Vite bundles the entry_client.tsx entry point.
+# No route scanning, no Remix framework features.
+ts_bundle(
+    name = "app_plain",
+    mode = "app",
+    html = "index.html",
+    entry_point = ":entry_client",
+    bundler = ":vite",
+    minify = False,
+    sourcemap = False,
+)
+
+# ── Remix SPA bundle (staging_srcs + vite_config) ────────────────────────────
+#
+# Uses staging_srcs to copy all app/ source files into a writable staging dir.
+# The Remix vitePlugin (via remix-vite.config.mjs) scans routes in the staging
+# dir and generates the route manifest.
+#
+# Output: app_remix_bundle/client/ containing:
+#   - index.html (Remix-generated entry with hashed asset references)
+#   - assets/*.js (route chunks: entry.client, root, _index, about, + vendors)
+#   - .vite/manifest.json (Vite build manifest)
+#
+# Run: bazel build //:app_remix
+ts_bundle(
+    name = "app_remix",
+    mode = "app",
+    html = "index.html",
+    entry_point = ":entry_client",
+    bundler = ":vite",
+    vite_config = "remix-vite.config.mjs",
+    # Stage the full project structure that Remix needs:
+    #   - package.json (required by Remix's config resolver)
+    #   - app/**/*.tsx (route files for route scanning)
+    #   - index.html (HTML entry point — staged so Rollup resolves it from
+    #     the staging root without '../' path traversal)
+    # The staging dir becomes vite.root so Remix finds:
+    #   package.json at <staging>/package.json
+    #   routes at <staging>/app/routes/*.tsx
+    staging_srcs = glob(
+        ["app/**/*.tsx"],
+        allow_empty = False,
+    ) + [
+        "package.json",
+        "index.html",
+    ],
+    minify = False,
+    sourcemap = False,
+    tags = ["manual"],
+)

examples/remix-app/MODULE.bazel

@@ -0,0 +1,34 @@
+"""Remix SPA example demonstrating staging_srcs in rules_typescript.
+
+Shows: React + Remix v2 SPA mode compilation, staging_srcs for route file
+staging, vite_config injection of the Remix Vite plugin, and how framework
+plugins interact with the Bazel sandbox.
+
+To use from BCR, remove the local_path_override block below.
+"""
+
+module(
+    name = "remix_app",
+    version = "0.0.0",
+)
+
+bazel_dep(name = "rules_typescript", version = "0.1.0")
+bazel_dep(name = "rules_shell", version = "0.6.1")
+
+register_toolchains("@rules_typescript//ts/toolchain:all")
+
+# ─── Local development only ───────────────────────────────────────────────────
+# Remove this block when publishing to BCR or using rules_typescript from the
+# Bazel Central Registry.
+local_path_override(
+    module_name = "rules_typescript",
+    path = "../..",
+)
+
+# ─── npm dependencies from pnpm-lock.yaml ────────────────────────────────────
+# Run `pnpm install` in this directory to update pnpm-lock.yaml.
+npm = use_extension("@rules_typescript//npm:extensions.bzl", "npm")
+npm.translate_lock(pnpm_lock = "//:pnpm-lock.yaml")
+use_repo(npm, "npm")
+
+bazel_dep(name = "gazelle", version = "0.47.0")

examples/remix-app/WORKSPACE.bazel

@@ -0,0 +1,3 @@
+# This workspace uses bzlmod (MODULE.bazel) exclusively.
+# This file prevents Bazel from searching parent directories for a WORKSPACE
+# file when the module is used as a local_path_override target.

examples/remix-app/app/entry.client.tsx

@@ -0,0 +1,32 @@
+/**
+ * Remix client entry point.
+ *
+ * In Remix SPA mode (ssr: false), this file is the browser entry that
+ * hydrates the React application.
+ *
+ * ── Bazel integration note ───────────────────────────────────────────────────
+ *
+ * This file is compiled by Bazel (ts_compile :entry_client) to produce
+ * bazel-bin/examples/remix-app/app/entry.client.js.
+ *
+ * It is ALSO staged by staging_srcs into _staging/app/entry.client.tsx so
+ * the Remix vitePlugin can discover it as the client entry.
+ *
+ * resolve.alias in the generated vite.config.mjs maps
+ * "app/entry.client" → the Bazel-compiled .js. However, Remix's virtual
+ * module system may resolve the entry differently — see BUILD.bazel for
+ * the honest limitations.
+ */
+
+import { RemixBrowser } from "@remix-run/react";
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <RemixBrowser />
+    </StrictMode>,
+  );
+});

examples/remix-app/app/root.tsx

@@ -0,0 +1,31 @@
+/**
+ * Root layout component for the Remix app.
+ *
+ * In Remix, root.tsx wraps all routes. It provides the HTML shell including
+ * the <head>, <body>, and the <Outlet> that renders matched child routes.
+ */
+
+import type { ReactElement, ReactNode } from "react";
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";
+
+export function Layout({ children }: { children: ReactNode }): ReactElement {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App(): ReactElement {
+  return <Outlet />;
+}

examples/remix-app/app/routes/_index.tsx

@@ -0,0 +1,29 @@
+/**
+ * Index route — renders the home page (/).
+ *
+ * Remix file-based routing: this file maps to the "/" route.
+ * The filename _index.tsx follows Remix v2 flat-file convention.
+ */
+
+import type { MetaFunction } from "@remix-run/react";
+import type React from "react";
+
+export const meta: MetaFunction = () => {
+  return [
+    { title: "Remix + rules_typescript" },
+    { name: "description", content: "A minimal Remix SPA example with Bazel." },
+  ];
+};
+
+export default function Index(): React.ReactElement {
+  return (
+    <div>
+      <h1>Welcome to Remix (rules_typescript)</h1>
+      <p>
+        This is a minimal Remix SPA app built with Bazel and rules_typescript.
+        Route files are staged into a writable directory so the Remix Vite plugin
+        can scan them and generate the route manifest.
+      </p>
+    </div>
+  );
+}

examples/remix-app/app/routes/about.tsx

@@ -0,0 +1,25 @@
+/**
+ * About route — renders the about page (/about).
+ *
+ * Remix file-based routing: this file maps to the "/about" route.
+ */
+
+import type { MetaFunction } from "@remix-run/react";
+import type React from "react";
+
+export const meta: MetaFunction = () => {
+  return [{ title: "About | Remix + rules_typescript" }];
+};
+
+export default function About(): React.ReactElement {
+  return (
+    <div>
+      <h1>About</h1>
+      <p>
+        This example demonstrates Remix SPA mode with Bazel and rules_typescript.
+        Routes are staged into a writable directory before bundling, allowing the
+        Remix Vite plugin to discover and process them.
+      </p>
+    </div>
+  );
+}

examples/remix-app/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Remix SPA (rules_typescript)</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./app/entry.client.js"></script>
+  </body>
+</html>