@agent-native/core 0.85.7 → 0.86.1

package/corpus/templates/design/server/lib/fusion-screens.ts

@@ -0,0 +1,246 @@
+/**
+ * fusion-screens — shared upsert logic for URL-backed screens on fusion
+ * (full-app) designs.
+ *
+ * Fusion screens are iframes of the app's container dev-server preview URL,
+ * the same rendering model as localhost screens (see `add-localhost-screens`)
+ * but keyed off `fusionApp.previewUrl` instead of a localhost connection.
+ * `screenMetadata[fileId]` is the single source the canvas reads to resolve
+ * source/previewUrl/dimensions (see `resolveScreenMetadata` in
+ * `MultiScreenCanvas.tsx`) — no parallel `fusionScreens` map is needed the way
+ * `localhostScreens` exists for localhost (that map is only consulted by the
+ * loopback-public-access heuristic in `server/db/index.ts`, which does not
+ * apply to fusion designs).
+ *
+ * Both `sync-fusion-app` and `add-fusion-screens` call `upsertFusionScreens`
+ * so the design_files + designs.data writes never diverge.
+ */
+
+import {
+  hasCollabState,
+  applyText,
+  seedFromText,
+} from "@agent-native/core/collab";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+
+import {
+  mergeCanvasFramePlacements,
+  parseCanvasFrameGeometryById,
+  type CanvasFramePlacement,
+} from "../../shared/canvas-frames.js";
+import { parseDesignDataBlob } from "../../shared/full-app.js";
+import { getDb, schema } from "../db/index.js";
+
+/** Default iframe viewport, mirroring add-localhost-screens' defaults. */
+export const DEFAULT_FUSION_SCREEN_WIDTH = 1280;
+export const DEFAULT_FUSION_SCREEN_HEIGHT = 900;
+
+export interface FusionScreenResult {
+  fileId: string;
+  filename: string;
+  path: string;
+  url: string;
+  title: string;
+  width: number;
+  height: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function slugForPath(path: string): string {
+  const slug = path
+    .replace(/^\/+/, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+  return (slug || "home").slice(0, 80);
+}
+
+function titleFromPath(path: string): string {
+  const trimmed = path.replace(/^\/+|\/+$/g, "");
+  if (!trimmed) return "Home";
+  const last = trimmed.split("/").pop() ?? trimmed;
+  return last.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function uniqueFilename(path: string, used: Set<string>): string {
+  const base = `fusion-${slugForPath(path)}.html`;
+  const [stem, extension = "html"] = base.split(/\.(?=[^.]+$)/);
+  let filename = `${stem}.${extension}`;
+  let suffix = 2;
+  while (used.has(filename)) {
+    filename = `${stem}-${suffix}.${extension}`;
+    suffix += 1;
+  }
+  used.add(filename);
+  return filename;
+}
+
+/**
+ * Create or refresh URL-backed screens pointing at `<previewUrl><path>` for a
+ * fusion-backed design. Read-modify-write on `designs.data`: preserves every
+ * other key (canvasFrames for non-fusion screens, tweaks, etc.).
+ */
+export async function upsertFusionScreens(args: {
+  designId: string;
+  previewUrl: string;
+  paths: string[];
+  width?: number;
+  height?: number;
+  startX?: number;
+  startY?: number;
+  gap?: number;
+}): Promise<{
+  screens: FusionScreenResult[];
+  placedFrames: Array<{
+    fileId: string;
+    filename?: string;
+    frame: CanvasFramePlacement;
+  }>;
+}> {
+  const {
+    designId,
+    previewUrl,
+    paths,
+    width = DEFAULT_FUSION_SCREEN_WIDTH,
+    height = DEFAULT_FUSION_SCREEN_HEIGHT,
+    startX = 0,
+    startY = 0,
+    gap = 160,
+  } = args;
+
+  if (paths.length === 0) {
+    throw new Error("At least one path is required to add fusion screens.");
+  }
+
+  const db = getDb();
+  const [design] = await db
+    .select({ data: schema.designs.data })
+    .from(schema.designs)
+    .where(eq(schema.designs.id, designId))
+    .limit(1);
+  const prevData = parseDesignDataBlob(design?.data);
+  const existingCanvasFrames = parseCanvasFrameGeometryById(
+    prevData.canvasFrames,
+  );
+  const existingMetadata = isRecord(prevData.screenMetadata)
+    ? { ...(prevData.screenMetadata as Record<string, unknown>) }
+    : {};
+  const existingFiles = await db
+    .select()
+    .from(schema.designFiles)
+    .where(eq(schema.designFiles.designId, designId));
+  const existingByFilename = new Map(
+    existingFiles.map((file) => [file.filename, file]),
+  );
+  const usedFilenames = new Set(existingFiles.map((file) => file.filename));
+  const now = new Date().toISOString();
+
+  const results: FusionScreenResult[] = [];
+  const placements: CanvasFramePlacement[] = [];
+
+  // Only place screens that don't already have canvas geometry so re-syncs
+  // never reset positions the user has arranged. New screens start after the
+  // right-most existing frame.
+  const existingGeometries = Object.values(existingCanvasFrames);
+  let nextX = startX;
+  if (existingGeometries.length > 0) {
+    nextX =
+      Math.max(
+        startX,
+        ...existingGeometries.map(
+          (frame) => (frame.x ?? 0) + (frame.width ?? width),
+        ),
+      ) + gap;
+  }
+
+  for (let index = 0; index < paths.length; index += 1) {
+    const path = paths[index]!;
+    const url = new URL(path, previewUrl).toString();
+    const preferredFilename = `fusion-${slugForPath(path)}.html`;
+    const existing = existingByFilename.get(preferredFilename);
+    const filename = existing?.filename ?? uniqueFilename(path, usedFilenames);
+    const fileId = existing?.id ?? nanoid();
+    const title = titleFromPath(path);
+
+    if (existing) {
+      await db
+        .update(schema.designFiles)
+        .set({ content: url, fileType: "html", updatedAt: now })
+        .where(eq(schema.designFiles.id, existing.id));
+      if (await hasCollabState(existing.id)) {
+        await applyText(existing.id, url, "content", "agent");
+      } else {
+        await seedFromText(existing.id, url);
+      }
+    } else {
+      await db.insert(schema.designFiles).values({
+        id: fileId,
+        designId,
+        filename,
+        fileType: "html",
+        content: url,
+        createdAt: now,
+        updatedAt: now,
+      });
+      await seedFromText(fileId, url);
+    }
+
+    results.push({ fileId, filename, path, url, title, width, height });
+    if (!existingCanvasFrames[fileId]) {
+      placements.push({
+        fileId,
+        filename,
+        x: nextX,
+        y: startY,
+        width,
+        height,
+        z: placements.length,
+      });
+      nextX += width + gap;
+    }
+  }
+
+  const mergedFrames = mergeCanvasFramePlacements({
+    existing: prevData.canvasFrames,
+    placements,
+    resolveFileId: (placement) => placement.fileId,
+  });
+
+  for (const screen of results) {
+    // Preserve user-adjusted title/dimensions on refresh; only the URL keys
+    // must always track the current preview URL.
+    const prevMeta = isRecord(existingMetadata[screen.fileId])
+      ? (existingMetadata[screen.fileId] as Record<string, unknown>)
+      : {};
+    existingMetadata[screen.fileId] = {
+      ...prevMeta,
+      sourceType: "fusion",
+      previewState: "live",
+      title: prevMeta.title ?? screen.title,
+      width: prevMeta.width ?? screen.width,
+      height: prevMeta.height ?? screen.height,
+      url: screen.url,
+      previewUrl: screen.url,
+      path: screen.path,
+    };
+  }
+
+  await db
+    .update(schema.designs)
+    .set({
+      data: JSON.stringify({
+        ...prevData,
+        canvasFrames: mergedFrames.canvasFrames,
+        screenMetadata: existingMetadata,
+        updatedAt: now,
+      }),
+      updatedAt: now,
+    })
+    .where(eq(schema.designs.id, designId));
+
+  return { screens: results, placedFrames: mergedFrames.placedFrames };
+}

package/corpus/templates/design/server/plugins/db.ts

@@ -1,6 +1,36 @@
-import { runMigrations } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+} from "@agent-native/core/db";
 
-export default runMigrations(
+import * as schema from "../db/schema.js";
+
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
+
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently — see the analytics template's v75-v83 incident
+// documented in templates/analytics/server/plugins/db.ts for the failure
+// class this guards against.
+const runDesignMigrations = runMigrations(
   [
     {
       version: 1,
@@ -269,6 +299,63 @@ CREATE INDEX IF NOT EXISTS motion_timeline_owner_org_updated_idx ON motion_timel
       version: 18,
       sql: {},
     },
+    // v19: design_fusion_edits — declared in schema.ts (queued AI edit intents
+    // for fusion-backed full-app designs) but never had a migration create the
+    // table, so any fresh/existing database without it 500s on first write.
+    // Named per the convention above since this is a new entry.
+    {
+      version: 19,
+      name: "design-fusion-edits-table",
+      sql: `CREATE TABLE IF NOT EXISTS design_fusion_edits (
+    id TEXT PRIMARY KEY,
+    design_id TEXT NOT NULL,
+    screen_file_id TEXT,
+    instruction TEXT NOT NULL,
+    target TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    batch_id TEXT,
+    error TEXT,
+    sent_at TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now')),
+    owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+    org_id TEXT,
+    visibility TEXT NOT NULL DEFAULT 'private'
+  )`,
+    },
   ],
   { table: "design_migrations" },
 );
+
+/**
+ * The migration list above is the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after it as a
+ * belt-and-braces safety net for the same failure mode fixed in the
+ * analytics template: a column added to schema.ts without a matching
+ * hand-written ALTER migration, which silently 500s every query touching a
+ * pre-existing production table. It only ever adds missing columns — never
+ * drops, renames, or retypes anything — and any failure here is logged and
+ * swallowed so it can never fail boot.
+ */
+export default async (nitroApp: any): Promise<void> => {
+  await runDesignMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
+};

package/corpus/templates/design/shared/collab-selection.ts

@@ -0,0 +1,52 @@
+/**
+ * Helpers for publishing resolvable agent selection descriptors into collab
+ * awareness so live viewers can render a selection ring over the element the
+ * agent is editing.
+ *
+ * The client (`RemoteSelectionRings`) resolves the descriptor's `selector`
+ * against the active screen's iframe via `querySelector`. A selector built
+ * from a stable `data-agent-native-node-id` is the most reliable anchor; a
+ * projection-derived CSS selector is the fallback. The optional `label`
+ * renders next to the ring (e.g. "AI — Editing button text").
+ */
+
+/** Escape a value for use inside a double-quoted CSS attribute selector. */
+export function escapeAttrValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Build a resolvable CSS selector for an edit target. Prefers the stable
+ * `data-agent-native-node-id` attribute; falls back to a projection selector.
+ * Returns `null` when neither is available.
+ */
+export function targetSelector(target: {
+  nodeId?: string | null;
+  selector?: string | null;
+}): string | null {
+  if (target.nodeId) {
+    return `[data-agent-native-node-id="${escapeAttrValue(target.nodeId)}"]`;
+  }
+  if (target.selector) return target.selector;
+  return null;
+}
+
+/** A selection descriptor consumed by `RemoteSelectionRings`. */
+export interface AgentSelectionDescriptor {
+  selector: string;
+  label?: string;
+}
+
+/**
+ * Build the `selection` awareness field for an edit target, or `null` when the
+ * target can't be resolved to a selector. When non-null, viewers render a ring
+ * labelled with `label` (kept short — a human-readable edit intent).
+ */
+export function agentSelectionDescriptor(
+  target: { nodeId?: string | null; selector?: string | null },
+  label?: string,
+): AgentSelectionDescriptor | null {
+  const selector = targetSelector(target);
+  if (!selector) return null;
+  return label ? { selector, label } : { selector };
+}

package/corpus/templates/design/shared/full-app.ts

@@ -0,0 +1,126 @@
+/**
+ * full-app — feature flag, types, and `designs.data` helpers for fusion-backed
+ * "full app" designs.
+ *
+ * A full-app design is backed by a real running app in a Builder Fusion
+ * container (one branch per design in the configured Builder project). Its
+ * screens are URL-backed iframes of the container's dev server — the same
+ * model as visual-edit/localhost screens, but remote — and edits queue in
+ * `design_fusion_edits` until they are applied by the in-container app agent.
+ *
+ * The `fusionApp` linkage lives in the design's `data` JSON blob (additive,
+ * like `screenMetadata`/`canvasFrames`), so no schema change is needed to mark
+ * a design as app-backed.
+ */
+
+/**
+ * Master switch for full app building in the Design app.
+ *
+ * Deliberately a plain code boolean for now: flip to `true` to expose the
+ * "Full app" creation option and enable the fusion app actions. Builder
+ * credentials plus a branch project id (DISPATCH_BUILDER_PROJECT_ID /
+ * BUILDER_BRANCH_PROJECT_ID / BUILDER_PROJECT_ID) are still required at
+ * runtime — without them the actions return the standard connect CTA.
+ */
+export const FULL_APP_BUILDING_ENABLED = false;
+
+export type DesignFusionAppStatus = "building" | "ready" | "error";
+
+export interface DesignFusionApp {
+  /** Builder project id the app branch lives in. */
+  projectId: string;
+  /** Branch backing this design (one branch per design). */
+  branchName: string;
+  /** Builder visual-editor URL for the branch (progress/debugging). */
+  editorUrl?: string;
+  /** Container dev-server URL once the container is ready; iframe-able. */
+  previewUrl?: string;
+  status: DesignFusionAppStatus;
+  /** Last provisioning/progress/error message. */
+  statusMessage?: string;
+  /** Reserved hosting slug — the app publishes to https://<slug>.builder.cloud */
+  hostingSlug?: string;
+  /** Public URL of the last successful deploy. */
+  deployedUrl?: string;
+  lastDeployId?: string;
+  lastDeployStatus?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** JSON target context attached to a queued fusion edit. */
+export interface FusionEditTarget {
+  /** CSS selector or data-node id of the element the user pointed at. */
+  selector?: string;
+  /** Route path of the screen the edit applies to (e.g. "/settings"). */
+  path?: string;
+  /** Full screen URL at edit time. */
+  url?: string;
+  /** Human-readable element description ("primary button", "nav logo"). */
+  nodeName?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Parse a design's raw `data` JSON string into an object (never throws). */
+export function parseDesignDataBlob(raw: unknown): Record<string, unknown> {
+  if (isRecord(raw)) return raw;
+  if (typeof raw !== "string" || !raw.trim()) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read the fusion app linkage from a design's `data` (raw JSON string or
+ * already-parsed object). Returns null when the design is not app-backed.
+ */
+export function readFusionApp(data: unknown): DesignFusionApp | null {
+  const blob = parseDesignDataBlob(data);
+  const app = blob.fusionApp;
+  if (!isRecord(app)) return null;
+  const projectId = typeof app.projectId === "string" ? app.projectId : "";
+  const branchName = typeof app.branchName === "string" ? app.branchName : "";
+  if (!projectId || !branchName) return null;
+  const status: DesignFusionAppStatus =
+    app.status === "ready" || app.status === "error" ? app.status : "building";
+  const str = (value: unknown): string | undefined =>
+    typeof value === "string" && value ? value : undefined;
+  return {
+    projectId,
+    branchName,
+    status,
+    editorUrl: str(app.editorUrl),
+    previewUrl: str(app.previewUrl),
+    statusMessage: str(app.statusMessage),
+    hostingSlug: str(app.hostingSlug),
+    deployedUrl: str(app.deployedUrl),
+    lastDeployId: str(app.lastDeployId),
+    lastDeployStatus: str(app.lastDeployStatus),
+    createdAt: str(app.createdAt) ?? "",
+    updatedAt: str(app.updatedAt) ?? "",
+  };
+}
+
+/**
+ * Return a new `data` object with the fusion app linkage written. Also stamps
+ * `sourceType/sourceMode: "fusion"` so capability resolution treats the design
+ * as fusion-backed. Additive — all other keys are preserved.
+ */
+export function writeFusionApp(
+  data: unknown,
+  app: DesignFusionApp,
+): Record<string, unknown> {
+  const blob = parseDesignDataBlob(data);
+  return {
+    ...blob,
+    sourceType: "fusion",
+    sourceMode: "fusion",
+    fusionApp: { ...app },
+  };
+}