@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/dist/index.js

@@ -0,0 +1,1053 @@
+import {
+  appIconSchema,
+  baseInput,
+  checkPermissionAppKinds,
+  checkSystemAppRoutes,
+  cloneAnd,
+  deepMergeConfig,
+  defineMethod,
+  home_exports,
+  host_exports,
+  isNetworkStrategy,
+  isVolumeStrategy,
+  numberInput,
+  peer_exports,
+  publicDomainValueSchema,
+  remote_exports
+} from "./chunk-O3UIK34B.js";
+import {
+  REALM_HOME_PROXY_CONTAINER_PATH,
+  nameSchema
+} from "./chunk-VHTUSZUX.js";
+import {
+  REF_SYMBOL,
+  SELF_APP_ID,
+  Service,
+  containsRef,
+  deferredRef,
+  identityRef,
+  interpolate,
+  ref
+} from "./chunk-AITGS27R.js";
+import {
+  HOME_COOKIE_PREFIX
+} from "./chunk-CMAEHQ4F.js";
+import "./chunk-MLKGABMK.js";
+
+// src/create-app.ts
+import { z as z3 } from "zod";
+
+// src/resolve.ts
+import { z as z2 } from "zod";
+
+// src/schema/build-apps.ts
+import { z } from "zod";
+var buildRecipeSchema = z.object({
+  dockerfile: z.string().optional(),
+  buildArgs: z.record(z.string(), z.string()).optional(),
+  context: z.string().optional()
+}).strict();
+var buildAppsSchema = z.array(
+  z.object({
+    appId: z.string(),
+    service: z.string(),
+    recipe: buildRecipeSchema
+  })
+);
+
+// src/resolve.ts
+var derivedBodySchema = z2.object({
+  kind: z2.literal("derived"),
+  appId: z2.string(),
+  name: z2.string()
+});
+var sharedBodySchema = z2.object({
+  kind: z2.literal("shared"),
+  providerAppId: z2.string(),
+  serviceKey: z2.string(),
+  name: z2.string()
+});
+var secretBodySchema = z2.object({ kind: z2.literal("secret"), path: z2.string() });
+function hasDeferredDescendant(value) {
+  if (value == null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasDeferredDescendant);
+  if ("__realmRef" in value) {
+    const m = value.__realmRef;
+    if (m && typeof m === "object") {
+      if (m.kind === "deferred") return true;
+      return hasDeferredDescendant(m);
+    }
+    return false;
+  }
+  for (const v of Object.values(value)) {
+    if (hasDeferredDescendant(v)) return true;
+  }
+  return false;
+}
+var deferredBodySchema = z2.object({
+  kind: z2.literal("deferred"),
+  id: z2.number().int().nonnegative(),
+  input: z2.unknown().refine((v) => !hasDeferredDescendant(v), {
+    message: "deferred input must not contain another deferred marker"
+  })
+});
+var concatLeafSchema = z2.discriminatedUnion("kind", [
+  derivedBodySchema,
+  sharedBodySchema,
+  secretBodySchema
+]);
+var concatBodySchema = z2.object({
+  kind: z2.literal("concat"),
+  parts: z2.array(z2.union([z2.string(), concatLeafSchema]))
+});
+var markerBodySchema = z2.discriminatedUnion("kind", [
+  derivedBodySchema,
+  sharedBodySchema,
+  secretBodySchema,
+  deferredBodySchema,
+  concatBodySchema
+]);
+var refMarkerSchema = z2.object({ __realmRef: markerBodySchema });
+var stringOrRef = z2.union([z2.string(), refMarkerSchema]);
+var hostPathSchema = z2.string().refine((p) => (p.startsWith("./") || p.startsWith("/")) && !p.includes(".."), {
+  message: "hostPath must start with ./ or / and must not contain .."
+});
+var RESERVED_PORTS = /* @__PURE__ */ new Set([
+  22,
+  // SSH on the worker host
+  3100,
+  // Home
+  3101,
+  // Home's dev uplink listener
+  6021
+  // The worker's verify relay
+]);
+var hostPortNumberSchema = z2.number().int().min(1, "hostPort must be >= 1").max(65535, "hostPort must be <= 65535").refine((p) => !RESERVED_PORTS.has(p), {
+  message: `hostPort must not be a Realm-reserved port (${[...RESERVED_PORTS].join(", ")})`
+});
+var imageReferenceSchema = z2.string().min(1, "image must not be empty").regex(
+  /^[a-z0-9_./\-:@]+$/,
+  "image must contain only Docker reference characters (a-z 0-9 _ . - / : @)"
+);
+var duration = (defaultSeconds) => z2.number().int().nonnegative().default(defaultSeconds);
+var healthcheckSchema = z2.object({
+  test: z2.array(z2.string()),
+  interval: duration(3),
+  timeout: duration(5),
+  retries: z2.number().int().nonnegative().default(10),
+  startPeriod: duration(10)
+});
+var containerPortSchema = z2.number().int().min(1).max(65535);
+var routerSchema = z2.object({
+  name: z2.string().min(1).optional(),
+  icon: appIconSchema.optional(),
+  // Home-screen tile opt-out. Absent = shown; `false` keeps the gated route
+  // but drops the tile (machine-facing endpoints like webhooks/registries).
+  // Optional rather than `.default(true)` so only opted-out routers carry
+  // the field in resolved state.
+  tile: z2.boolean().optional(),
+  containerPort: containerPortSchema,
+  // The whole resolved `r.home.publicDomain()` value, hosts and redirect mode
+  // together. No `stringOrRef` arm: that would let a bare author-supplied
+  // string in through the back door, which is what the permission closes.
+  // Absent when the app declares no such permission or none was granted.
+  publicDomain: publicDomainValueSchema.optional(),
+  pathPrefix: z2.string().regex(/^\/[a-zA-Z0-9/_-]*$/, "pathPrefix must start with / and contain only [a-zA-Z0-9/_-]").optional(),
+  compress: z2.boolean().default(true),
+  maxRequestSizeMb: z2.number().nullable().default(4),
+  rateLimit: z2.union([
+    z2.number(),
+    z2.object({
+      requests: z2.number(),
+      window: z2.string().regex(/^\d+(ms|s|m|h)$/, "window must be a duration like 10s, 1m, 1h")
+    })
+  ]).nullable().default({ requests: 1e3, window: "10s" }),
+  headers: z2.record(z2.string(), z2.string().nullable()).optional()
+});
+var hostPortSchema = z2.object({
+  containerPort: containerPortSchema,
+  hostPort: hostPortNumberSchema,
+  protocol: z2.enum(["tcp", "udp"]).optional()
+});
+var backupStrategySchema = z2.discriminatedUnion("kind", [
+  z2.object({ kind: z2.literal("file-copy") }),
+  z2.object({ kind: z2.literal("sqlite"), file: z2.string() }),
+  z2.object({
+    kind: z2.literal("pg-dump"),
+    url: stringOrRef,
+    version: z2.number().int().positive()
+  }),
+  z2.object({ kind: z2.literal("valkey-save"), url: stringOrRef }),
+  z2.object({
+    kind: z2.literal("mysql-dump"),
+    url: stringOrRef,
+    version: z2.number().int().positive()
+  })
+]);
+var absoluteContainerPath = z2.string().startsWith("/", {
+  message: "containerPath must be absolute (start with '/')"
+});
+var homeServiceSchema = z2.object({
+  // Exactly one of `image` / `build` is present (enforced in the
+  // superRefine below). `image` is the prebuilt-pull path; `build` is the
+  // build-from-source path, which has no pinned digest until its first
+  // build, so Home leaves the app inert until one is set.
+  image: imageReferenceSchema.optional(),
+  // `build: true` is author sugar for the default recipe — normalize it to
+  // `{}` here so `HomeService.build` is always a `BuildRecipe` object.
+  // The image/build XOR (superRefine below) reads the transformed value, so
+  // `true`/`{}` both count as "build present".
+  build: z2.literal(true).or(buildRecipeSchema).transform((v) => v === true ? {} : v).optional(),
+  router: routerSchema.optional(),
+  hostPorts: z2.array(hostPortSchema).optional(),
+  env: z2.record(z2.string(), z2.union([stringOrRef, z2.number()])).optional(),
+  files: z2.record(absoluteContainerPath, stringOrRef).optional(),
+  command: z2.array(stringOrRef).optional(),
+  volumes: z2.array(
+    z2.object({
+      hostPath: hostPathSchema,
+      containerPath: absoluteContainerPath,
+      // Silo-owned group. Present only on a Silo's volume entry; the
+      // renderer derives `group_add` from it and the grant gate matches
+      // (hostPath, gid) against the Silos the app joined.
+      gid: z2.number().int().positive().optional(),
+      readOnly: z2.boolean().optional(),
+      backup: z2.union([backupStrategySchema, z2.literal(false)]).optional()
+    })
+  ).optional(),
+  gpu: z2.boolean().optional(),
+  iptables: z2.boolean().optional(),
+  joinNetworks: z2.array(z2.string()).optional(),
+  healthcheck: healthcheckSchema.optional(),
+  memory: z2.string().optional(),
+  cpu: z2.number().positive().max(128).optional(),
+  replicas: z2.number().int().min(1).max(100).default(1),
+  labels: z2.array(z2.string()).optional(),
+  shmSizeMb: z2.number().int().positive().optional()
+}).strict().superRefine((svc, ctx) => {
+  if (svc.image == null && svc.build == null) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["image"],
+      message: "a service must set either `image` or `build`"
+    });
+  } else if (svc.image != null && svc.build != null) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["build"],
+      message: "a service cannot set both `image` and `build`"
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, vol] of (svc.volumes ?? []).entries()) {
+    if (seen.has(vol.containerPath)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["volumes", i, "containerPath"],
+        message: `containerPath ${vol.containerPath} is mounted by two volumes`
+      });
+    }
+    seen.add(vol.containerPath);
+  }
+  if (!svc.files || !svc.volumes) return;
+  const volumePaths = new Set(svc.volumes.map((v) => v.containerPath));
+  for (const fileKey of Object.keys(svc.files)) {
+    if (volumePaths.has(fileKey)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["files", fileKey],
+        message: `containerPath ${fileKey} is used by both files: and volumes:`
+      });
+    }
+  }
+});
+var requestManifestSchema = z2.object({
+  method: z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z2.string(),
+  query: z2.record(z2.string(), z2.union([z2.string(), z2.number(), z2.boolean()])).optional(),
+  body: z2.unknown().optional()
+});
+var loaderManifestSchema = z2.object({
+  service: z2.string(),
+  port: z2.number().int().positive().max(65535),
+  headers: z2.record(z2.string(), stringOrRef).optional(),
+  outputSchema: z2.unknown(),
+  merge: z2.literal(true).optional()
+});
+var actionManifestSchema = z2.object({
+  service: z2.string(),
+  port: z2.number().int().positive().max(65535),
+  headers: z2.record(z2.string(), stringOrRef).optional(),
+  inputSchema: z2.unknown(),
+  outputSchema: z2.unknown().optional()
+});
+var baseSurfaceManifestSchema = z2.object({
+  title: z2.string().min(1),
+  // Icon name from `@yourrealm/sdk/ui/components/icons.tsx` named exports.
+  // Runtime is just `string` (the TS-side `IconName` union catches
+  // typos at authoring time); the Home sidebar falls back to a default
+  // glyph if a value isn't a known export, so a typo doesn't 500.
+  icon: z2.string().min(1),
+  // The surface's live UI state + settings schemas (JSON Schema form).
+  // `configSchema` (built from the config leaves' zod schemas) lets Home
+  // validate a submitted config; `stateSchema`'s `{}`-parse seeds the
+  // runtime's initial state.
+  stateSchema: z2.unknown().optional(),
+  configSchema: z2.unknown().optional(),
+  // The config form's render descriptor: one `ConfigFieldLeaf` per
+  // `r.input.*` leaf (type/label/placeholder/default/enum values/bounds),
+  // so the tile's config screen reuses the same field renderer the app
+  // install/edit form uses. Absent when the surface takes no config.
+  configFields: z2.unknown().optional(),
+  // The surface's resolved config: each leaf's `.prefill()` default,
+  // shipped to the iframe as the base layer for every loader's
+  // request(state, config) (Home merges the placement's persisted config
+  // over it).
+  defaultConfig: z2.unknown().optional(),
+  loaders: z2.record(z2.string(), loaderManifestSchema).optional(),
+  actions: z2.record(z2.string(), actionManifestSchema).optional()
+});
+var widgetManifestSchema = baseSurfaceManifestSchema.extend({
+  cols: z2.number().int().min(1).default(2),
+  rows: z2.number().int().min(1).default(2)
+});
+var uiManifestSchema = z2.object({
+  pages: z2.record(z2.string(), baseSurfaceManifestSchema).optional(),
+  widgets: z2.record(z2.string(), widgetManifestSchema).optional()
+});
+var headerFieldSchema = z2.object({ field: z2.enum(["username", "email"]) });
+var headerSegmentSchema = z2.union([z2.string(), headerFieldSchema]);
+var authHeaderSourceSchema = z2.union([
+  headerFieldSchema,
+  z2.object({ literal: z2.string() }),
+  z2.object({ template: z2.array(headerSegmentSchema) })
+]);
+var trustedHeadersManifestSchema = z2.object({
+  keys: z2.array(z2.string()),
+  byRole: z2.record(z2.enum(["admin", "member"]), z2.record(z2.string(), authHeaderSourceSchema))
+});
+var homeAppSchema = z2.object({
+  services: z2.record(nameSchema, homeServiceSchema),
+  egress: z2.literal(true).optional(),
+  ui: uiManifestSchema.optional(),
+  trustedHeaders: trustedHeadersManifestSchema.optional(),
+  // True when the app declares verifyAnonymousRequest. Home-side only (never
+  // crosses to the worker wire); recompute reads it to register the app's
+  // routed hosts in the anonymous-gate cache.
+  hasAnonymousGate: z2.boolean().optional(),
+  // Single = run on one selected worker (default). System = fan out to
+  // every compatible worker. Drives the install panel's picker and the
+  // Home's UI fan-out behavior. See platform/docs realm-ts/workers.mdx.
+  kind: z2.enum(["single", "system"]).default("single")
+});
+function resolveDesiredApp(state, opts = {}) {
+  const resolvedServices = {};
+  for (const [key, service] of Object.entries(state.services ?? {})) {
+    if (service instanceof Service) {
+      const qualifiedKey = opts.appId ? `${opts.appId}_${key}` : key;
+      service._setServiceKey(qualifiedKey);
+      resolvedServices[key] = service.getServiceDefinition();
+    } else {
+      resolvedServices[key] = service;
+    }
+  }
+  const serialized = JSON.parse(JSON.stringify({ ...state, services: resolvedServices }));
+  return homeAppSchema.parse(serialized);
+}
+
+// src/http-header.ts
+var HEADER_NAME_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+var HEADER_VALUE_RE = /^[\x20-\x7e]*$/;
+
+// src/types.ts
+function isTab(node) {
+  return node.kind === "node.tab";
+}
+function isSection(node) {
+  return node.kind === "node.section";
+}
+function isInput(node) {
+  return typeof node.kind === "string" && node.kind.startsWith("input.");
+}
+
+// src/create-app.ts
+var IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertValidKeys(schema, prefix = "") {
+  for (const [key, node] of Object.entries(schema)) {
+    if (!IDENT_RE.test(key)) {
+      const where = prefix ? `at "${prefix}.${key}"` : `at "${key}"`;
+      throw new Error(
+        `configSchema key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ ${where} - use identifier-shaped names (letters, digits, underscore)`
+      );
+    }
+    if (isTab(node) || isSection(node)) {
+      assertValidKeys(node.children, prefix ? `${prefix}.${key}` : key);
+    }
+  }
+}
+function assertSchemaHomogeneous(schema) {
+  const keys = Object.keys(schema);
+  if (keys.length === 0) return;
+  const tabs = keys.filter((k) => isTab(schema[k]));
+  if (tabs.length > 0 && tabs.length !== keys.length) {
+    const first = tabs[0];
+    const other = keys.find((k) => !isTab(schema[k]));
+    throw new Error(
+      `configSchema must be either all r.tab(...) or none - "${first}" is a tab, "${other}" is not`
+    );
+  }
+}
+function collectPermissionNodes(schema, out = {}, prefix = "") {
+  for (const [key, node] of Object.entries(schema)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isTab(node) || isSection(node)) {
+      collectPermissionNodes(node.children, out, path);
+    } else if (!isInput(node)) {
+      out[path] = node;
+    }
+  }
+  return out;
+}
+var OMIT = /* @__PURE__ */ Symbol("omit");
+function buildConfigShape(schema) {
+  const out = {};
+  for (const [key, node] of Object.entries(schema)) {
+    const built = buildNodeShape(node);
+    if (built !== OMIT) out[key] = built;
+  }
+  return out;
+}
+function buildNodeShape(node) {
+  if (isTab(node)) {
+    const sub = {};
+    for (const [k, child] of Object.entries(node.children)) {
+      const built = buildNodeShape(child);
+      if (built !== OMIT) sub[k] = built;
+    }
+    return sub;
+  }
+  if (isSection(node)) {
+    if (node.meta.isOptional) return OMIT;
+    const sub = {};
+    for (const [k, child] of Object.entries(node.children)) {
+      const built = buildNodeShape(child);
+      if (built !== OMIT) sub[k] = built;
+    }
+    return sub;
+  }
+  if (isInput(node)) {
+    const value = node.meta.prefill;
+    if (value !== void 0) return value;
+    return OMIT;
+  }
+  return OMIT;
+}
+var AUTH_ROLES = ["admin", "member"];
+function sampleTrustedHeaders(fn) {
+  const keys = /* @__PURE__ */ new Set();
+  const byRole = {};
+  for (const role of AUTH_ROLES) {
+    const out = fn({ username: identityRef("username"), email: identityRef("email"), role });
+    const map = {};
+    for (const [key, value] of Object.entries(out)) {
+      if (!HEADER_NAME_RE.test(key)) {
+        throw new Error(
+          `getTrustedHeaders["${key}"]: not a valid HTTP header name (letters, digits, and !#$%&'*+-.^_\`|~). Every call into the app carries these headers, and a malformed name is rejected outright`
+        );
+      }
+      if (key.toLowerCase().startsWith("x-realm-")) {
+        throw new Error(
+          `getTrustedHeaders["${key}"]: the X-Realm-* namespace is reserved for the platform. Home and the worker stamp headers there and clients are stripped of them, so a container can trust them; pick a name outside it`
+        );
+      }
+      keys.add(key);
+      map[key] = toTrustedHeaderSource(key, value);
+    }
+    byRole[role] = map;
+  }
+  return { keys: [...keys], byRole };
+}
+function assertHeaderLiteral(key, text2) {
+  if (HEADER_VALUE_RE.test(text2)) return;
+  throw new Error(
+    `getTrustedHeaders["${key}"]: value must be printable ASCII. A character outside it is rejected on the way into the container, failing every call the app makes`
+  );
+}
+function toTrustedHeaderSource(key, value) {
+  if (typeof value === "string") {
+    assertHeaderLiteral(key, value);
+    return { literal: value };
+  }
+  if (typeof value === "object" && value !== null && REF_SYMBOL in value) {
+    const json = value.toJSON();
+    if (typeof json === "string") {
+      assertHeaderLiteral(key, json);
+      return { literal: json };
+    }
+    const marker = json.__realmRef;
+    if (marker.kind === "identity") return { field: identityField(key, marker.field) };
+    if (marker.kind === "concat") {
+      return { template: (marker.parts ?? []).map((part) => headerSegment(key, part)) };
+    }
+  }
+  throw new Error(`getTrustedHeaders["${key}"]: value must be a user field or a literal string`);
+}
+function headerSegment(key, part) {
+  if (typeof part === "string") {
+    assertHeaderLiteral(key, part);
+    return part;
+  }
+  const m = part;
+  if (m?.kind === "identity") return { field: identityField(key, m.field) };
+  throw new Error(
+    `getTrustedHeaders["${key}"]: only user fields (user.username / user.email) and literal text can compose a header value`
+  );
+}
+function identityField(key, field) {
+  if (field === "username" || field === "email") return field;
+  throw new Error(`getTrustedHeaders["${key}"]: unknown user field "${field}"`);
+}
+function assertBaseSurface(surface, where) {
+  if (typeof surface.title !== "string" || surface.title.length === 0) {
+    throw new Error(`${where}.title must be a non-empty string`);
+  }
+  if (typeof surface.icon !== "string" || surface.icon.length === 0) {
+    throw new Error(`${where}.icon must be a non-empty string from the icon registry`);
+  }
+  if (typeof surface.render !== "function") {
+    throw new Error(`${where}.render must be a function`);
+  }
+  if (surface.loaders) {
+    for (const [lk, l] of Object.entries(surface.loaders)) {
+      if (!IDENT_RE.test(lk)) {
+        throw new Error(`${where}.loaders key "${lk}" must be an identifier`);
+      }
+      if (typeof l.service !== "string" || typeof l.port !== "number") {
+        throw new Error(`${where}.loaders.${lk} needs a string service and a number port`);
+      }
+      if (typeof l.request !== "function") {
+        throw new Error(`${where}.loaders.${lk}.request must be a (state, config) => request fn`);
+      }
+    }
+  }
+  if (surface.actions) {
+    for (const [ak, a] of Object.entries(surface.actions)) {
+      if (!IDENT_RE.test(ak)) {
+        throw new Error(`${where}.actions key "${ak}" must be an identifier`);
+      }
+      if (typeof a.service !== "string" || typeof a.port !== "number") {
+        throw new Error(`${where}.actions.${ak} needs a string service and a number port`);
+      }
+      if (typeof a.request !== "function") {
+        throw new Error(`${where}.actions.${ak}.request must be an (input, config) => request fn`);
+      }
+    }
+  }
+}
+function assertPageMap(pages) {
+  for (const [key, p] of Object.entries(pages)) {
+    if (!IDENT_RE.test(key)) {
+      throw new Error(
+        `ui.pages key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ at "${key}" - use identifier-shaped names (letters, digits, underscore)`
+      );
+    }
+    assertBaseSurface(p, `ui.pages.${key}`);
+  }
+}
+function assertWidgetMap(widgets) {
+  for (const [key, w] of Object.entries(widgets)) {
+    if (!IDENT_RE.test(key)) {
+      throw new Error(
+        `ui.widgets key must match /^[a-zA-Z_][a-zA-Z0-9_]*$/ at "${key}" - use identifier-shaped names (letters, digits, underscore)`
+      );
+    }
+    assertBaseSurface(w, `ui.widgets.${key}`);
+    for (const dim of ["cols", "rows"]) {
+      const v = w[dim];
+      if (v === void 0) continue;
+      if (!Number.isInteger(v) || v < 1) {
+        throw new Error(`ui.widgets.${key}.${dim} must be an integer \u2265 1`);
+      }
+    }
+  }
+}
+function assertValidUi(ui) {
+  if (ui.pages) assertPageMap(ui.pages);
+  if (ui.widgets) assertWidgetMap(ui.widgets);
+}
+function assertMergeMatchesKind(ui, kind) {
+  const visit = (where, surface) => {
+    if (!surface.loaders) return;
+    for (const [name, l] of Object.entries(surface.loaders)) {
+      const hasMerge = typeof l.merge === "function";
+      if (kind === "system" && !hasMerge) {
+        throw new Error(
+          `${where}.loaders.${name}: createSystemApp requires merge(results) on every loader`
+        );
+      }
+      if (kind === "single" && hasMerge) {
+        throw new Error(
+          `${where}.loaders.${name}: createApp forbids merge \u2014 only one worker responds`
+        );
+      }
+    }
+  };
+  if (ui.pages) for (const [k, p] of Object.entries(ui.pages)) visit(`ui.pages.${k}`, p);
+  if (ui.widgets) for (const [k, w] of Object.entries(ui.widgets)) visit(`ui.widgets.${k}`, w);
+}
+function headerToManifest(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && REF_SYMBOL in value) {
+    const json = value.toJSON();
+    return json;
+  }
+  throw new Error("ui proxy headers must be strings or refs (e.g. r.stableSecret(...))");
+}
+function headersToManifest(headers) {
+  if (!headers) return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k] = headerToManifest(v);
+  return out;
+}
+function toJsonSchemaSafe(schema) {
+  try {
+    return z3.toJSONSchema(schema);
+  } catch (e) {
+    if (e instanceof Error && e.message.includes("cannot be represented in JSON Schema")) {
+      return {};
+    }
+    throw e;
+  }
+}
+function loaderToManifest(loader) {
+  const manifest = {
+    outputSchema: toJsonSchemaSafe(loader.outputSchema),
+    service: loader.service,
+    port: loader.port,
+    headers: headersToManifest(loader.headers)
+  };
+  if (loader.merge) manifest.merge = true;
+  if (manifest.headers === void 0) delete manifest.headers;
+  return manifest;
+}
+function actionToManifest(action) {
+  const manifest = {
+    inputSchema: toJsonSchemaSafe(action.inputSchema),
+    service: action.service,
+    port: action.port,
+    headers: headersToManifest(action.headers)
+  };
+  if (action.outputSchema) manifest.outputSchema = toJsonSchemaSafe(action.outputSchema);
+  if (manifest.headers === void 0) delete manifest.headers;
+  return manifest;
+}
+function describeSurfaceConfig(schema) {
+  const fields = {};
+  const shape = {};
+  const defaultConfig = {};
+  for (const [key, node] of Object.entries(schema)) {
+    if (!isInput(node)) {
+      throw new Error(
+        `ui surface configSchema "${key}": only r.input.* leaves are allowed (no permissions, tabs, or sections).`
+      );
+    }
+    if (node.kind === "input.secret") {
+      throw new Error(
+        `ui surface configSchema "${key}": r.input.secret() isn't supported in a surface config - a widget config holds display settings, not credentials. Declare the secret in the app's top-level configSchema and pass its ref to a loader header.`
+      );
+    }
+    const specific = node.kind.slice("input.".length);
+    const meta = node.meta ?? {};
+    const leaf = { type: specific };
+    if (meta.title) leaf.label = meta.title;
+    if (meta.placeholder !== void 0) leaf.placeholder = meta.placeholder;
+    if (meta.prefill !== void 0) {
+      leaf.default = meta.prefill;
+      defaultConfig[key] = meta.prefill;
+    }
+    if (meta.description) leaf.description = meta.description;
+    if (meta.isOptional) leaf.optional = true;
+    if (specific === "enum" && "values" in node) {
+      leaf.values = [...node.values];
+    }
+    if (specific === "number") {
+      if (meta.int) leaf.step = 1;
+      if (meta.min !== void 0) leaf.min = meta.min;
+      if (meta.max !== void 0) leaf.max = meta.max;
+    }
+    fields[key] = leaf;
+    shape[key] = meta.isOptional || meta.prefill !== void 0 ? node.schema.optional() : node.schema;
+  }
+  return { fields, defaultConfig, validation: z3.object(shape) };
+}
+function surfaceToManifest(s) {
+  const manifest = { title: s.title, icon: s.icon };
+  if (s.stateSchema) manifest.stateSchema = toJsonSchemaSafe(s.stateSchema);
+  if (s.loaders) {
+    manifest.loaders = {};
+    for (const [k, l] of Object.entries(s.loaders)) {
+      manifest.loaders[k] = loaderToManifest(l);
+    }
+  }
+  if (s.actions) {
+    manifest.actions = {};
+    for (const [k, a] of Object.entries(s.actions)) {
+      manifest.actions[k] = actionToManifest(a);
+    }
+  }
+  return manifest;
+}
+function widgetToManifest(w) {
+  const manifest = {
+    ...surfaceToManifest(w),
+    cols: w.cols ?? 2,
+    rows: w.rows ?? 2
+  };
+  if (w.configSchema) {
+    const { fields, defaultConfig, validation } = describeSurfaceConfig(
+      w.configSchema
+    );
+    manifest.configFields = fields;
+    manifest.configSchema = toJsonSchemaSafe(validation);
+    manifest.defaultConfig = defaultConfig;
+  }
+  return manifest;
+}
+function buildUiManifest(ui) {
+  const manifest = {};
+  if (ui.pages) {
+    manifest.pages = {};
+    for (const [k, p] of Object.entries(ui.pages)) {
+      if (p.configSchema) {
+        throw new Error(
+          `ui page "${k}": only widgets can be configured \u2014 move the configSchema to a widget or drop it.`
+        );
+      }
+      manifest.pages[k] = surfaceToManifest(p);
+    }
+  }
+  if (ui.widgets) {
+    manifest.widgets = {};
+    for (const [k, w] of Object.entries(ui.widgets)) {
+      manifest.widgets[k] = widgetToManifest(w);
+    }
+  }
+  return manifest;
+}
+function buildApp(kind, options) {
+  const schema = options.configSchema;
+  if (schema) {
+    assertValidKeys(schema);
+    assertSchemaHomogeneous(schema);
+    const scopeViolations = checkPermissionAppKinds(kind, collectPermissionNodes(schema));
+    if (scopeViolations.length > 0) {
+      const factory = kind === "system" ? "createSystemApp" : "createApp";
+      throw new Error(`${factory}: ${scopeViolations.map((v) => v.description).join("; ")}`);
+    }
+  }
+  if (options.info && kind === "system") {
+    throw new Error(
+      `createSystemApp: \`info\` is not supported \u2014 a fanned-out service has no single URL for services.<name> to resolve to`
+    );
+  }
+  if (options.ui) {
+    assertValidUi(options.ui);
+    assertMergeMatchesKind(options.ui, kind);
+  }
+  let uiManifest = options.ui ? buildUiManifest(options.ui) : void 0;
+  const app = {
+    name: options.name,
+    description: options.description,
+    kind,
+    verifyAnonymousRequest: options.verifyAnonymousRequest,
+    configSchema: options.configSchema,
+    ui: options.ui,
+    info: options.info,
+    attachSurfaces(ui) {
+      if (app.ui) {
+        throw new Error(
+          "createApp: `ui` is already set \u2014 remove the inline `ui:` block to use file-based surfaces (pages/*, widgets/*), or delete the surface files."
+        );
+      }
+      assertValidUi(ui);
+      assertMergeMatchesKind(ui, kind);
+      app.ui = ui;
+      uiManifest = buildUiManifest(ui);
+    },
+    evaluate({ config, appId, preview }) {
+      const shaped = schema ? deepMergeConfig(
+        buildConfigShape(schema),
+        config ?? {}
+      ) : config;
+      const state = options.getDesiredState({ config: shaped, preview: preview ?? null });
+      const withExtras = {
+        ...state,
+        ...options.getTrustedHeaders ? { trustedHeaders: sampleTrustedHeaders(options.getTrustedHeaders) } : {},
+        ...options.verifyAnonymousRequest ? { hasAnonymousGate: true } : {},
+        ...uiManifest ? { ui: uiManifest } : {}
+      };
+      const resolved = resolveDesiredApp({ ...withExtras, kind }, { appId });
+      if (kind === "system") {
+        const violations = checkSystemAppRoutes(resolved);
+        if (violations.length > 0) {
+          throw new Error(violations.map((v) => v.description).join("; "));
+        }
+      }
+      return resolved;
+    }
+  };
+  return app;
+}
+function createApp(options) {
+  return buildApp("single", options);
+}
+function createSystemApp(options) {
+  if (options.getTrustedHeaders) {
+    throw new Error(
+      "createSystemApp: `getTrustedHeaders` is not supported \u2014 header brokering happens on an authenticated subdomain, and a system app has no routes"
+    );
+  }
+  if (options.verifyAnonymousRequest) {
+    throw new Error(
+      "createSystemApp: `verifyAnonymousRequest` is not supported \u2014 anonymous gates admit callers to an app's routes, and a system app has none"
+    );
+  }
+  return buildApp("system", options);
+}
+
+// src/index.ts
+import { z as z6 } from "zod";
+
+// src/schema/inputs.ts
+import { z as z4 } from "zod";
+var text = baseInput("input.text", z4.string());
+var secret = baseInput("input.secret", z4.string());
+var number = numberInput("input.number", z4.number());
+var boolean = baseInput("input.boolean", z4.boolean());
+function enum_(values) {
+  const record = baseInput("input.enum", z4.enum(values))();
+  return cloneAnd(record, { values });
+}
+
+// src/schema/nodes.ts
+function section(children) {
+  const record = {
+    kind: "node.section",
+    children,
+    meta: { isOptional: false }
+  };
+  defineMethod(record, "title", function(text2) {
+    return cloneAnd(this, { meta: { ...this.meta, title: text2 } });
+  });
+  defineMethod(record, "describe", function(text2) {
+    return cloneAnd(this, { meta: { ...this.meta, description: text2 } });
+  });
+  defineMethod(record, "optional", function() {
+    return cloneAnd(this, { meta: { ...this.meta, isOptional: true } });
+  });
+  return record;
+}
+function tab(children) {
+  const record = {
+    kind: "node.tab",
+    children,
+    meta: {}
+  };
+  defineMethod(record, "title", function(text2) {
+    return cloneAnd(this, { meta: { ...this.meta, title: text2 } });
+  });
+  defineMethod(record, "describe", function(text2) {
+    return cloneAnd(this, { meta: { ...this.meta, description: text2 } });
+  });
+  return record;
+}
+
+// src/stable-secret.ts
+function stableSecret(name) {
+  return ref({ kind: "derived", appId: SELF_APP_ID, name });
+}
+
+// src/runtime/docker/home-proxy-server/protocol.ts
+import { z as z5 } from "zod";
+var MAX_PATH = 2048;
+var SAFE_SUBPATH = /^\/[A-Za-z0-9._~/?=&%-]*$/;
+function isSafeSubPath(p) {
+  if (!SAFE_SUBPATH.test(p)) return false;
+  if (p.includes("..")) return false;
+  if (p.includes("//")) return false;
+  return true;
+}
+var homeProxyRequestSchema = z5.object({
+  method: z5.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z5.string().min(1).max(MAX_PATH).refine(isSafeSubPath, { message: "unsafe path" }),
+  body: z5.unknown().optional()
+}).strict();
+var homeProxyResponseSchema = z5.object({
+  status: z5.number().int(),
+  body: z5.unknown()
+}).strict();
+
+// src/runtime/home-client/index.ts
+async function callHome(method, path, body, opts = {}) {
+  const socketPath = opts.socketPath ?? REALM_HOME_PROXY_CONTAINER_PATH;
+  const conn = await Deno.connect({ transport: "unix", path: socketPath });
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder("utf-8");
+  try {
+    const line = JSON.stringify(body === void 0 ? { method, path } : { method, path, body });
+    await conn.write(encoder.encode(line + "\n"));
+    const buf = new Uint8Array(8192);
+    let remainder = "";
+    while (true) {
+      const n = await conn.read(buf);
+      if (n === null) break;
+      remainder += decoder.decode(buf.slice(0, n), { stream: true });
+      const nl = remainder.indexOf("\n");
+      if (nl !== -1) {
+        const raw = remainder.slice(0, nl).trim();
+        const parsed = homeProxyResponseSchema.parse(JSON.parse(raw));
+        return { status: parsed.status, body: parsed.body };
+      }
+    }
+    throw new Error("home proxy closed without a response line");
+  } finally {
+    try {
+      conn.close();
+    } catch {
+    }
+  }
+}
+
+// src/apply.ts
+function registry() {
+  const g = globalThis;
+  let fns = g.__realm_deferred_fns;
+  if (!fns) {
+    fns = [];
+    g.__realm_deferred_fns = fns;
+  }
+  return fns;
+}
+function apply(input, fn) {
+  const fns = registry();
+  const id = fns.length;
+  fns.push(fn);
+  return deferredRef({ kind: "deferred", id, input });
+}
+
+// src/yaml.ts
+import { stringify } from "yaml";
+
+// src/serialize.ts
+function serializeRefs(value, serialize) {
+  if (!containsRef(value)) return serialize(value);
+  return apply(value, serialize);
+}
+
+// src/yaml.ts
+function toYaml(value) {
+  return serializeRefs(value, (resolved) => stringify(resolved));
+}
+
+// src/ini.ts
+function scalar(value) {
+  return typeof value === "boolean" ? value ? "true" : "false" : String(value);
+}
+function emitIni(value) {
+  const orphans = [];
+  const sections = [];
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "object" && v !== null) {
+      sections.push([k, v]);
+    } else {
+      orphans.push([k, v]);
+    }
+  }
+  let out = "";
+  for (const [k, v] of orphans) out += `${k} = ${scalar(v)}
+`;
+  for (const [section2, body] of sections) {
+    if (out.length > 0) out += "\n";
+    out += `[${section2}]
+`;
+    for (const [k, v] of Object.entries(body)) {
+      out += `${k} = ${scalar(v)}
+`;
+    }
+  }
+  return out;
+}
+function toIni(value) {
+  return serializeRefs(value, emitIni);
+}
+
+// src/json.ts
+function toJson(value) {
+  return serializeRefs(value, (resolved) => JSON.stringify(resolved));
+}
+
+// src/xml.ts
+function escapeXmlText(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function emit(parts, indent, key, value) {
+  parts.push(`${indent}<${key}>`);
+  if (typeof value === "string") {
+    parts.push(escapeXmlText(value));
+  } else if (typeof value === "number") {
+    parts.push(String(value));
+  } else {
+    parts.push("\n");
+    for (const [k, v] of Object.entries(value)) {
+      emit(parts, indent + "  ", k, v);
+    }
+    parts.push(indent);
+  }
+  parts.push(`</${key}>
+`);
+}
+function toXml(value) {
+  return serializeRefs(value, (resolved) => {
+    const parts = [];
+    for (const [k, v] of Object.entries(resolved)) {
+      emit(parts, "", k, v);
+    }
+    return parts.join("");
+  });
+}
+
+// src/index.ts
+var r = {
+  host: host_exports,
+  peers: peer_exports,
+  remote: remote_exports,
+  home: home_exports,
+  input: {
+    text,
+    secret,
+    number,
+    boolean,
+    enum: enum_
+  },
+  section,
+  tab,
+  stableSecret
+};
+export {
+  HOME_COOKIE_PREFIX,
+  apply,
+  callHome,
+  createApp,
+  createSystemApp,
+  interpolate,
+  isNetworkStrategy,
+  isVolumeStrategy,
+  nameSchema,
+  r,
+  ref,
+  toIni,
+  toJson,
+  toXml,
+  toYaml,
+  z6 as z
+};