@agent-native/core 0.97.0 → 0.98.0

package/corpus/templates/design/app/pages/design-editor/generation-prompt-directives.ts

@@ -0,0 +1,180 @@
+import { callAction } from "@agent-native/core/client";
+import type { TweakDefinition } from "@shared/api";
+
+import type { UploadedFile } from "@/components/editor/PromptDialog";
+
+export function formatUploadedFileContext(files: UploadedFile[]): string {
+  if (files.length === 0) return "";
+
+  const lines: string[] = [
+    "",
+    `The user uploaded ${files.length} file(s) for context:`,
+  ];
+
+  files.forEach((file, index) => {
+    lines.push(
+      `${index + 1}. ${file.originalName} (${file.type}, ${(file.size / 1024).toFixed(1)}KB) at path: ${file.path}`,
+    );
+    const text = file.textContent?.trim();
+    if (text) {
+      lines.push(
+        `Extracted text${file.textTruncated ? " (truncated)" : ""}:\n${text}`,
+      );
+    }
+  });
+
+  return lines.join("\n");
+}
+
+export function imageAttachmentsFromUploadedFiles(
+  files: UploadedFile[],
+): string[] {
+  return files
+    .map((file) => file.dataUrl)
+    .filter((dataUrl): dataUrl is string => !!dataUrl?.trim());
+}
+
+export function formatTweakDefinitionsContext(
+  tweaks: TweakDefinition[],
+): string {
+  if (tweaks.length === 0) return "None yet.";
+  return JSON.stringify(
+    tweaks.map((tweak) => ({
+      id: tweak.id,
+      label: tweak.label,
+      type: tweak.type,
+      cssVar: tweak.cssVar,
+      defaultValue: tweak.defaultValue,
+      options: tweak.options,
+      min: tweak.min,
+      max: tweak.max,
+      step: tweak.step,
+    })),
+    null,
+    2,
+  );
+}
+
+export function designSystemGenerationDirectives(
+  designSystemId?: string | null,
+): string[] {
+  if (!designSystemId) return [];
+  return [
+    `Use design system id "${designSystemId}" for this generation.`,
+    "Use the selected design system context in this message as mandatory generation input. If details are missing or conflict, call `get-design-system` for that id before writing visual code.",
+    `When calling \`generate-design\`, pass \`designSystemId: "${designSystemId}"\` so the design remains linked.`,
+  ];
+}
+
+interface DesignSystemGenerationContextResult {
+  title?: string;
+  agentContext?: string;
+}
+
+export async function loadDesignSystemGenerationContext(
+  designSystemId?: string | null,
+): Promise<string> {
+  if (!designSystemId) return "";
+  try {
+    const result = (await callAction(
+      "get-design-system",
+      { id: designSystemId },
+      { method: "GET" },
+    )) as DesignSystemGenerationContextResult | undefined;
+    if (result?.agentContext?.trim()) {
+      return [
+        "",
+        result.agentContext.trim(),
+        "",
+        "The selected design system context above was hydrated before this agent run. Follow it directly; do not replace it with generic colors, fonts, spacing, or components.",
+      ].join("\n");
+    }
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "unknown loading error";
+    return [
+      "",
+      "## Selected Design System Context",
+      `The selected design system id "${designSystemId}" could not be loaded before generation: ${message}`,
+      "Before writing visual code, call `get-design-system` for this id. If it still fails, stop and tell the user the selected design system is unavailable instead of improvising a generic style.",
+    ].join("\n");
+  }
+  return [
+    "",
+    "## Selected Design System Context",
+    `The selected design system id "${designSystemId}" returned no generation context.`,
+    "Call `get-design-system` for this id before writing visual code. If it still has no usable tokens/docs, stop and ask the user to finish design-system indexing instead of improvising a generic style.",
+  ].join("\n");
+}
+
+export function designIntakeQuestionDirectives(
+  designId: string,
+  designSystemId?: string | null,
+): string[] {
+  return [
+    `This is a new UI-started design for design id "${designId}". The design shell already exists - DO NOT call create-design.`,
+    ...designSystemGenerationDirectives(designSystemId),
+    "First, call `show-design-questions` with 4-6 tailored questions and then stop. Do NOT call generate-design or present-design-variants until the user submits or skips the questions.",
+    "Make the questions feel like Claude Design intake: form factor, aesthetic direction, important features/content, special interactions/polish, and whether to explore variations. Omit or rephrase anything the user's prompt already answered.",
+    "Use concise option chips with `allowOther: true`; include a practical `Decide for me` option where useful. Use `multiSelect: true` for feature/interactions questions.",
+    "Set a specific title like `Quick questions about your todo app` and a short description. After `show-design-questions` succeeds, wait for the user's answers.",
+  ];
+}
+
+export function promptRequestsVariantExploration(prompt: string): boolean {
+  const normalized = prompt.toLowerCase();
+  const asksForVariants =
+    /\b(variant|variants|variation|variations|direction|directions|option|options|concept|concepts|exploration|explorations)\b/.test(
+      normalized,
+    );
+  if (!asksForVariants) return false;
+  return (
+    /\b(2|3|4|5|two|three|four|five|multiple|several|distinct|different|choose|compare|side[-\s]?by[-\s]?side)\b/.test(
+      normalized,
+    ) || /\bto choose from\b/.test(normalized)
+  );
+}
+
+export function designVariantGenerationDirectives(
+  designId: string,
+  designSystemId?: string | null,
+): string[] {
+  return [
+    `Use the \`present-design-variants --designId="${designId}"\` action first. The design already exists - DO NOT call create-design.`,
+    ...designSystemGenerationDirectives(designSystemId),
+    "The user's prompt already asks to explore multiple directions, so DO NOT call `show-design-questions` first and DO NOT call `generate-design` first.",
+    "Call `present-design-variants` with 2-5 concise directions (3 when unspecified). Prefer label, description, accentColor, and feature bullets; omit large content HTML when needed because the action can render compact representative screens. Every web design must be responsive; default each desktop direction to width 1440 and height 1024. Use mobile dimensions only when the user explicitly requested a mobile-first primary artboard.",
+    'Wait for the user\'s chat pick, delete each unchosen variant screen at most once, call `get-design-snapshot` exactly once with `fileId` for the kept screen, then call `edit-design` exactly once on that same `fileId` in a bounded pass. Use `mode: "replace-file"` when expanding the representative placeholder into a complete but compact product UI in the chosen direction. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the feature list is too large for one reliable edit. Do not repeat delete/snapshot cycles. Do not call `generate-design` after a variant pick. Stop after the first successful `edit-design` save.',
+  ];
+}
+
+export function designGenerationDirectives(
+  designId: string,
+  designSystemId?: string | null,
+): string[] {
+  return [
+    `Use the \`generate-design --designId="${designId}"\` action with exactly one complete, renderable \`index.html\` file first. The design already exists - DO NOT call create-design.`,
+    ...designSystemGenerationDirectives(designSystemId),
+    'If the user asked to explore variations, call `present-design-variants` with 2-5 concise directions. Prefer label, description, accentColor, and feature bullets; omit large content HTML when needed because the action can render compact representative screens. Wait for their chat pick, delete each unchosen variant screen at most once, call `get-design-snapshot` exactly once with `fileId` for the kept screen, then call `edit-design` exactly once on that same `fileId` in a bounded pass. Use `mode: "replace-file"` when expanding the representative placeholder into a complete but compact product UI in the chosen direction. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the feature list is too large for one reliable edit. Do not repeat delete/snapshot cycles. Do not call `generate-design` after a variant pick. Stop after the first successful `edit-design` save. Otherwise generate one polished first direction.',
+    'Responsive behavior is mandatory for every web design: use a mobile-first layout, include a viewport meta tag, stack or collapse desktop columns at narrow widths, and never rely on a fixed-width desktop shell. Default to a desktop primary artboard. For a Desktop or Both/responsive intake answer, pass `primaryViewport: "desktop"` and `canvasFrames` with width 1440 and height 1024; pass `primaryViewport: "mobile"` only when the user explicitly chooses a mobile-primary artboard.',
+    "Keep the first pass bounded enough to finish quickly: one self-contained Alpine.js + Tailwind CDN HTML document, polished but concise. Add 3-6 tweaks only when they naturally fit the design.",
+    "After generate-design succeeds, run `take-design-screenshot` at desktop and mobile viewports. Fix any horizontal overflow or layout breakage with edit-design before summarizing what was created.",
+  ];
+}
+
+export function designTemplateRefinementDirectives(
+  designId: string,
+  templateId: string,
+  designSystemId?: string | null,
+): string[] {
+  return [
+    `This design was copied from template "${templateId}". Its files, canvas dimensions, defaults, and locked layers already exist.`,
+    ...designSystemGenerationDirectives(designSystemId),
+    `Call \`get-design-snapshot --designId="${designId}"\` exactly once before editing.`,
+    "Refine the existing template with `edit-design`; do not call `generate-design`, `delete-file`, or create a replacement screen.",
+    'Layers marked `data-agent-native-locked="true"` and everything inside them must remain byte-for-byte unchanged. The server rejects changes to locked backgrounds, logos, and other fixed template layers.',
+    "Preserve canvasFrames and the template's width and height. Change only the unlocked content needed for the user's request.",
+    "Prefer one bounded search-replace edit pass. Use replace-file only when necessary, and keep every locked subtree exactly as it appeared in the snapshot.",
+    "After edit-design succeeds, stop and summarize the refinement.",
+  ];
+}

package/corpus/templates/design/app/pages/design-editor/html-layer-positioning.ts

@@ -0,0 +1,226 @@
+import { normalizePoisonedBoardNestedCoords } from "@shared/board-file";
+import type { CodeLayerNode } from "@shared/code-layer";
+
+import { authoredElementPosition } from "@/components/design/multi-screen/primitive-drop-target";
+
+import { escapeHtmlAttributeValue } from "./dom-utils";
+
+const ABS_POSITION_PROPS = [
+  "position",
+  "left",
+  "top",
+  "right",
+  "bottom",
+] as const;
+
+// Flex/grid-item-only inline properties. Mirrors FLEX_ITEM_INLINE_PROPS in
+// editor-chrome.bridge.ts's prepareFlowMembersForAbsoluteDrop (the live
+// in-iframe optimistic strip) — a former flow child persisted here as
+// position:absolute must lose these too, or the source round-trip re-adds
+// back exactly the flex-item styling the live DOM already dropped, and any
+// later reparent back into flow (including undo) resurrects a stale,
+// source-parent-relative grow/shrink/basis/align-self/order.
+const FLEX_ITEM_PROPS = [
+  "flex",
+  "flex-grow",
+  "flex-shrink",
+  "flex-basis",
+  "align-self",
+  "order",
+] as const;
+
+/**
+ * Remove absolute-positioning style properties from the element identified by
+ * `data-agent-native-node-id` so that it becomes a flow child after being
+ * reparented into a container. Returns the updated HTML, or the original HTML
+ * if the node cannot be found or parsing is unavailable.
+ *
+ * Uses DOMParser + CSSStyleDeclaration.removeProperty() rather than
+ * applyVisualEdit({kind:"style",value:""}) because the substrate rejects
+ * empty-string values in isSafeStyleValue, making that approach a silent no-op.
+ */
+export function removeAbsolutePositioningFromNodeInHtml(
+  content: string,
+  nodeAttrId: string,
+): string {
+  if (typeof window === "undefined") return content;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const element = doc.querySelector(
+      `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
+    ) as HTMLElement | null;
+    if (!element) return content;
+    for (const prop of ABS_POSITION_PROPS) {
+      element.style.removeProperty(prop);
+    }
+    return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+  } catch {
+    return content;
+  }
+}
+
+/** Persist the bridge's narrow fallback for a flow insertion whose authored
+ * stylesheet still resolves the moved child to absolute/fixed after its
+ * editable inline/utility positioning has been stripped. `!important` is
+ * intentional: the stylesheet declaration that forced this path may itself
+ * be important. Left/top are removed because they are inert in static flow
+ * and should not become surprising offsets if positioning changes later. */
+export function setFlowPositioningOverrideForNodeInHtml(
+  content: string,
+  nodeAttrId: string,
+): string {
+  if (typeof window === "undefined") return content;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const element = doc.querySelector(
+      `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
+    ) as HTMLElement | null;
+    if (!element) return content;
+    for (const prop of ABS_POSITION_PROPS) {
+      element.style.removeProperty(prop);
+    }
+    element.style.setProperty("position", "static", "important");
+    return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+  } catch {
+    return content;
+  }
+}
+
+export function setAbsolutePositioningForNodeInHtml(
+  content: string,
+  nodeAttrId: string,
+  point: { x: number; y: number },
+  pointerOffset?: { x: number; y: number },
+): string {
+  if (typeof window === "undefined") return content;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const element = doc.querySelector(
+      `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
+    ) as HTMLElement | null;
+    if (!element) return content;
+    element.style.position = "absolute";
+    element.style.left = `${Math.round(point.x - (pointerOffset?.x ?? 0))}px`;
+    element.style.top = `${Math.round(point.y - (pointerOffset?.y ?? 0))}px`;
+    element.style.removeProperty("right");
+    element.style.removeProperty("bottom");
+    for (const prop of FLEX_ITEM_PROPS) {
+      element.style.removeProperty(prop);
+    }
+    return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+  } catch {
+    return content;
+  }
+}
+
+export function getAbsolutePositioningForNodeInHtml(
+  content: string,
+  nodeAttrId: string,
+): { x: number; y: number } | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const element = doc.querySelector(
+      `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
+    ) as HTMLElement | null;
+    if (!element) return null;
+    // Walk every ancestor up to <body> (authoredElementPosition, shared with
+    // MultiScreenCanvas's drop-target math) instead of reading only this
+    // node's own inline left/top. A node nested two-plus containers deep has
+    // a style.left/top that's relative to its OWN immediate parent, not the
+    // screen root, so a flat read here previously fed
+    // computeReparentedChildPosition two positions from different coordinate
+    // spaces whenever the source/target containers weren't both direct
+    // children of the screen root — producing a garbage delta and making the
+    // dropped element jump away from the cursor. For a root-level node this
+    // walk terminates after one step and returns the exact same left/top as
+    // before, so root-level reparents are unaffected.
+    return authoredElementPosition(element);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Finding 4: normalizePoisonedBoardNestedCoords (shared/board-file.ts)
+ * heuristically rewrites persisted nested board coords with no built-in
+ * trace of its own (kept side-effect-free so it stays safely callable from
+ * any context — see its doc comment). Every call site that applies its
+ * result and persists it goes through this shared logger instead, so a bad
+ * heuristic firing in the wild is visible: file id, how many nodes were
+ * rebased, and a small before/after sample.
+ */
+export function warnIfPoisonedBoardCoordsNormalized(
+  fileId: string,
+  result: ReturnType<typeof normalizePoisonedBoardNestedCoords>,
+): void {
+  if (!result.changed) return;
+  console.warn(
+    "[design] normalized poisoned nested board coordinates on load/reparent",
+    {
+      fileId,
+      fixedNodeCount: result.fixedNodeCount,
+      samples: result.samples,
+    },
+  );
+}
+
+export function isAbsoluteCodeLayerNode(
+  node: CodeLayerNode | null | undefined,
+) {
+  const position = String(node?.style.position ?? "").toLowerCase();
+  return position === "absolute" || position === "fixed";
+}
+
+export function setCodeLayerAttributeInHtml(
+  content: string,
+  node: CodeLayerNode,
+  name: string,
+  value: string | null,
+): string | null {
+  if (!node.source) return null;
+  const openStart = node.source.openStart;
+  const openEnd = node.source.openEnd;
+  if (openStart < 0 || openEnd <= openStart || openEnd > content.length) {
+    return null;
+  }
+
+  const openTag = content.slice(openStart, openEnd);
+  const attrPattern = new RegExp(
+    `\\s${name}(?:\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s"'=<>]+))?`,
+    "i",
+  );
+  const replacement =
+    value === null || value === ""
+      ? ""
+      : ` ${name}="${escapeHtmlAttributeValue(value)}"`;
+
+  if (attrPattern.test(openTag)) {
+    const nextOpenTag = openTag.replace(attrPattern, replacement);
+    return `${content.slice(0, openStart)}${nextOpenTag}${content.slice(openEnd)}`;
+  }
+
+  if (value === null || value === "") return content;
+  const insertAt = openTag.endsWith("/>") ? openEnd - 2 : openEnd - 1;
+  return `${content.slice(0, insertAt)}${replacement}${content.slice(insertAt)}`;
+}
+
+export function getBodyInlineStyles(content: string): Record<string, string> {
+  if (typeof window === "undefined") return {};
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const body = doc.body;
+    if (!body) return {};
+    return {
+      backgroundColor: body.style.backgroundColor,
+      backgroundImage: body.style.backgroundImage,
+      backgroundPosition: body.style.backgroundPosition,
+      backgroundRepeat: body.style.backgroundRepeat,
+      backgroundSize: body.style.backgroundSize,
+      fontFamily: body.style.fontFamily,
+      fontSize: body.style.fontSize,
+    };
+  } catch {
+    return {};
+  }
+}