@yahoo/uds-create-sidecar 3.0.0

package/README.md

@@ -0,0 +1,220 @@
+# UDS Create Sidecar
+
+`@yahoo/uds-create-sidecar` lets an Expo development build render Create
+previews inside the customer's own app. The preview therefore uses the same
+native packages, configuration, and package versions as that app.
+
+The package contains the existing Sidecar pairing UI, preview-room client,
+authenticated and integrity-checked bundle loader, and renderer host. The only
+required component prop is an explicit module registry:
+
+```text
+Create browser ── signed room token ──> UDSCreateSidecar
+                                           │
+Customer app ── exact modules + versions ──┘
+                                           │
+                                           └──> real app dependencies
+```
+
+The standalone app in `apps/create-sidecar` consumes this same package and is
+the reference implementation.
+
+## Requirements
+
+This first package targets Expo SDK 57 development builds with React Native
+0.86. It is not supported in Expo Go because registered packages may contain
+native code.
+
+Install the host and the shared JSON renderer as development dependencies:
+
+```sh
+bun add --dev --exact @yahoo/uds-create-sidecar @json-render/react
+bunx expo install react-native-safe-area-context
+```
+
+Install and configure every native package used by the design system in the
+usual way. Sidecar does not replace that package's native setup.
+`UDSCreateSidecar` must be rendered below the app's `SafeAreaProvider`.
+
+### What the package expects from the app
+
+Every package Sidecar needs from the app is a declared peer dependency, so a
+missing one is reported at install time:
+
+- `react`, `react-native`, `react-native-safe-area-context`, and `expo` are the
+  app's own copies. Sidecar renders its pairing UI with them.
+- `@json-render/react` is the renderer every Create preview bundle imports.
+  Sidecar never imports it itself, but the registry requires it as a module,
+  so the app must install it and register it.
+
+### What the package carries
+
+The preview-room client is built on Yjs and the Hocuspocus provider. Both are
+compiled into the package, together with their `lib0` and `y-protocols`
+internals, so the app does not install them and the app's own versions never
+matter. Compiling them in also lets the package replace `lib0`'s Web Crypto
+binding with a small shim over `@noble/hashes`, the package's one runtime
+dependency, so React Native needs no Web Crypto polyfill. Yjs uses those values
+only for client and document identifiers.
+
+An app that also uses Yjs sees one console error the first time the Sidecar
+screen loads, `Yjs was already imported`, shown as a LogBox error in a
+development build. It is Yjs noticing a second copy of itself. Sidecar's
+documents never cross into the app's Yjs, so the two copies never meet and the
+message can be dismissed.
+
+## 1. Define the host registry
+
+Create one module that statically imports everything a downloaded preview may
+use. Metro must see these imports when it builds the app; downloaded JavaScript
+cannot discover or import an arbitrary installed native package later.
+
+This example exposes `react-native-maps`, a package that is intentionally not
+built into the standalone Sidecar:
+
+```tsx
+// src/create-sidecar-registry.ts
+import * as JsonRenderReact from "@json-render/react";
+import { createUDSCreateSidecarRegistry } from "@yahoo/uds-create-sidecar/registry";
+import * as React from "react";
+import * as ReactJsxRuntime from "react/jsx-runtime";
+import * as ReactNative from "react-native";
+import * as ReactNativeMaps from "react-native-maps";
+import appPackage from "../package.json";
+
+export const createSidecarRegistry = createUDSCreateSidecarRegistry({
+  hostName: "Acme mobile app",
+  hostVersion: appPackage.version,
+  modules: {
+    "@json-render/react": JsonRenderReact,
+    react: React,
+    "react/jsx-runtime": ReactJsxRuntime,
+    "react-native": ReactNative,
+    "react-native-maps": ReactNativeMaps,
+  },
+  packageVersions: {
+    ...appPackage.dependencies,
+    ...appPackage.devDependencies,
+  },
+});
+```
+
+The versions for every exposed package must be exact strings such as `1.2.3`,
+not ranges such as `^1.2.3`. Pin those dependencies in `package.json` or provide
+exact versions from the app's lockfile. The registry rejects a missing or
+non-exact version immediately.
+
+Subpath imports must be registered separately, but they use the package root's
+version. For example, registering `react/jsx-dev-runtime` still uses the
+`react` version.
+
+### How Create checks the registry
+
+Each preview build lists the packages it imports, the version the design system
+declares for each, and the exact import paths it reads. The connected host
+advertises the registry, and Create and the phone run the same comparison:
+
+- A required package or import path that is not registered is missing.
+- A registered version whose major or minor differs from the required version
+  is a mismatch. Patch versions may differ.
+
+While the phone is connected, Create's phone controls name the packages the
+host cannot provide. The phone repeats the check before evaluating a bundle and
+refuses with an error naming the package and, for a mismatch, both versions.
+Either side can move: install the version the design system declares, or update
+the version the design system declares for that package.
+
+## 2. Add a development-only route
+
+The app, rather than the component, owns the production gate. This lets the
+standalone Sidecar remain a normal release build while a customer app can make
+the route impossible to activate in production.
+
+For Expo Router, guard the package load as well as the rendered route:
+
+```tsx
+// app/create-preview.tsx
+import { Redirect } from "expo-router";
+import { createSidecarRegistry } from "../src/create-sidecar-registry";
+
+declare const require: (
+  id: "@yahoo/uds-create-sidecar",
+) => typeof import("@yahoo/uds-create-sidecar");
+
+export default function CreatePreviewRoute() {
+  if (!__DEV__) return <Redirect href="/" />;
+
+  const { UDSCreateSidecar } = require("@yahoo/uds-create-sidecar");
+  return <UDSCreateSidecar registry={createSidecarRegistry} />;
+}
+```
+
+Use the equivalent compile-time development constant and production fallback
+with another router. Do not gate only a navigation link: the route itself must
+return before loading or rendering Sidecar. The package test compiles this
+pattern with `__DEV__` set to false and verifies that the Sidecar reference is
+removed from the route's execution path.
+
+The two entry points are split for this gate. `@yahoo/uds-create-sidecar/registry`
+holds only the registry builder, imports nothing, and is safe to import at
+module top level in every build, including production. The root entry holds the
+pairing UI, the preview-room client, and the compiled-in Yjs, so it stays behind
+the compile-time check.
+
+## 3. Pair with Create
+
+Open the development route. `UDSCreateSidecar` uses production Create by
+default and shows the same origin chooser, short-code pairing, status UI,
+disconnect behavior, and full-screen design preview as the standalone app. A
+custom origin remains selected while the component is mounted; a new launch
+returns to production.
+
+It also accepts an existing Sidecar deep link when the host app routes that URL
+to the component; short-code pairing is the portable default for an embedded
+host with its own URL scheme.
+
+When the host router mounts this screen from a deep link, pass the route values
+to the component. This avoids relying on a link event that may have fired before
+the route mounted:
+
+```tsx
+import type { UDSCreateSidecarDeepLink } from "@yahoo/uds-create-sidecar";
+import { useLocalSearchParams } from "expo-router";
+
+const params = useLocalSearchParams<UDSCreateSidecarDeepLink>();
+const deepLink =
+  params.origin && params.room && params.token && params.ws
+    ? {
+        origin: params.origin,
+        room: params.room,
+        token: params.token,
+        ws: params.ws,
+      }
+    : undefined;
+
+return (
+  <UDSCreateSidecar registry={createSidecarRegistry} deepLink={deepLink} />
+);
+```
+
+Create's QR code uses the `uds-create-sidecar` scheme. An embedded app must
+route that scheme to its development-only preview screen to use QR pairing.
+Apps that do not own that route should use the short pairing code.
+
+In Create, open **Connect phone**, choose **Connect Sidecar**, and enter the
+code from the app. The embedded host advertises the registry's exact package
+versions through the existing preview protocol; no protocol or token changes
+are required.
+
+## Security boundary
+
+The host downloads a bundle only from the selected Create origin, sends the
+room-scoped bearer token, limits the response to 5 MiB, and verifies the
+manifest's SHA-256 hash before evaluation. Module resolution is limited to the
+explicit registry.
+
+This is not a JavaScript sandbox. An authorized Create bundle runs inside the
+development app's JavaScript process and can use normal JavaScript globals in
+addition to registered modules. Expose only modules intended for preview, use
+only a trusted Create deployment, and keep the route hard-disabled in
+production.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { UDSCreateSidecarModules, UDSCreateSidecarRegistry, UDSCreateSidecarRegistryOptions, createUDSCreateSidecarRegistry } from "./registry.js";
+import * as _$react from "react";
+
+//#region src/deep-link.d.ts
+interface UDSCreateSidecarDeepLink {
+  readonly origin: string;
+  readonly room: string;
+  readonly token: string;
+  readonly ws: string;
+}
+declare function parseUDSCreateSidecarDeepLink(url: string): UDSCreateSidecarDeepLink | undefined;
+//#endregion
+//#region src/UDSCreateSidecar.d.ts
+interface UDSCreateSidecarProps {
+  readonly registry: UDSCreateSidecarRegistry;
+  /** Pairing values read by the host router from its current deep link. */
+  readonly deepLink?: UDSCreateSidecarDeepLink;
+}
+declare function UDSCreateSidecar({
+  deepLink,
+  registry
+}: UDSCreateSidecarProps): _$react.JSX.Element;
+//#endregion
+export { UDSCreateSidecar, type UDSCreateSidecarDeepLink, type UDSCreateSidecarModules, type UDSCreateSidecarProps, type UDSCreateSidecarRegistry, type UDSCreateSidecarRegistryOptions, createUDSCreateSidecarRegistry, parseUDSCreateSidecarDeepLink };