@drawcall/design 0.8.1 → 0.9.0

package/dist/v1/schemas.js

@@ -58,6 +58,10 @@ export const httpUrlSchema = z
     .url()
     .refine(isHttpUrl, "URLs must use HTTP or HTTPS");
 export const imageUrlSchema = httpUrlSchema;
+export const imageInputSchema = z.union([
+    z.file().mime(["image/png", "image/jpeg", "image/webp"]),
+    imageUrlSchema,
+]);
 /** An absolute path in the hosted project filesystem. */
 export const projectPathSchema = z.string().max(1_024).refine(isProjectPath, {
     message: "Project paths must be absolute and cannot contain empty, . or .. segments",
@@ -122,33 +126,45 @@ export const gltsFrameSchema = frameBaseSchema.extend({
 });
 export const imageGenerationOperationSchema = z.enum(["generate", "edit"]);
 export const imageGenerationResultSchema = z.enum(["new", "replace"]);
-export const imageGenerationReferenceSchema = z.object({
-    frameId: designIdSchema,
-    frameUpdatedAt: z.string().datetime(),
-});
+const imageGenerationDigestSchema = z
+    .string()
+    .regex(/^[a-f0-9]{64}$/, "Image generation digests must be SHA-256 hex");
+export const imageInputProvenanceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("url"),
+        url: imageUrlSchema,
+        digest: imageGenerationDigestSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("file"),
+        name: z
+            .string()
+            .trim()
+            .min(1)
+            .max(255)
+            .refine(isFileName, "Image filenames cannot contain path separators"),
+        digest: imageGenerationDigestSchema,
+    })
+        .strict(),
+]);
 export const IMAGE_GENERATION_PROVIDER = "fal-ai";
 export const IMAGE_GENERATION_MODEL = "openai/gpt-image-2";
-export const LEGACY_IMAGE_GENERATION_PROVIDER = "cloudflare-workers-ai";
-export const LEGACY_IMAGE_GENERATION_MODEL = "@cf/black-forest-labs/flux-2-klein-4b";
 const imageGenerationProvenanceBaseSchema = z.object({
     kind: z.literal("generated"),
     operation: imageGenerationOperationSchema,
     prompt: z.string().min(1).max(MAX_IMAGE_GENERATION_PROMPT_LENGTH),
     references: z
-        .array(imageGenerationReferenceSchema)
+        .array(imageInputProvenanceSchema)
         .max(MAX_IMAGE_GENERATION_REFERENCES),
     result: imageGenerationResultSchema,
 });
-export const imageGenerationProvenanceSchema = z.discriminatedUnion("provider", [
-    imageGenerationProvenanceBaseSchema.extend({
-        provider: z.literal(IMAGE_GENERATION_PROVIDER),
-        model: z.literal(IMAGE_GENERATION_MODEL),
-    }),
-    imageGenerationProvenanceBaseSchema.extend({
-        provider: z.literal(LEGACY_IMAGE_GENERATION_PROVIDER),
-        model: z.literal(LEGACY_IMAGE_GENERATION_MODEL),
-    }),
-]);
+export const imageGenerationProvenanceSchema = imageGenerationProvenanceBaseSchema.extend({
+    provider: z.literal(IMAGE_GENERATION_PROVIDER),
+    model: z.literal(IMAGE_GENERATION_MODEL),
+});
 export const imageFrameSchema = frameBaseSchema.extend({
     type: z.literal("image"),
     file: projectFilePathSchema,
@@ -179,10 +195,7 @@ export const createGltsFrameSchema = createFrameBaseSchema
 export const createImageFrameSchema = createFrameBaseSchema
     .extend({
     type: z.literal("image"),
-    image: z.union([
-        z.file().mime(["image/png", "image/jpeg", "image/webp"]),
-        imageUrlSchema,
-    ]),
+    image: imageInputSchema,
 })
     .strict();
 export const createMarketFrameSchema = createFrameBaseSchema
@@ -196,85 +209,56 @@ export const createFrameSchema = z.discriminatedUnion("type", [
     createImageFrameSchema,
     createMarketFrameSchema,
 ]);
-export const generateImageFrameSchema = z
-    .object({
+const imageGenerationPromptSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(MAX_IMAGE_GENERATION_PROMPT_LENGTH);
+const imageGenerationBase = {
     project: designIdSchema,
-    operation: imageGenerationOperationSchema,
-    prompt: z.string().trim().min(1).max(MAX_IMAGE_GENERATION_PROMPT_LENGTH),
-    target: designIdSchema.optional(),
-    references: z
-        .array(designIdSchema)
-        .max(MAX_IMAGE_GENERATION_REFERENCES)
-        .default([]),
-    result: imageGenerationResultSchema,
-    name: frameNameSchema.optional(),
+    prompt: imageGenerationPromptSchema,
+};
+const newGeneratedFrame = {
+    result: z.literal("new"),
+    name: frameNameSchema,
     x: framePositionSchema.optional(),
     y: framePositionSchema.optional(),
-})
-    .strict()
-    .superRefine((input, context) => {
-    const orderedReferences = [
-        ...(input.target ? [input.target] : []),
-        ...input.references,
-    ];
-    if (new Set(orderedReferences).size !== orderedReferences.length) {
-        context.addIssue({
-            code: "custom",
-            path: ["references"],
-            message: "Image references must be unique",
-        });
-    }
-    if (orderedReferences.length > MAX_IMAGE_GENERATION_REFERENCES) {
-        context.addIssue({
-            code: "custom",
-            path: ["references"],
-            message: `Image generation supports at most ${MAX_IMAGE_GENERATION_REFERENCES} references`,
-        });
-    }
-    if (input.operation === "generate" && input.target) {
-        context.addIssue({
-            code: "custom",
-            path: ["target"],
-            message: "A generation request cannot have an edit target",
-        });
-    }
-    if (input.operation === "edit" && !input.target) {
-        context.addIssue({
-            code: "custom",
-            path: ["target"],
-            message: "An edit request requires an image target",
-        });
-    }
-    if (input.result === "replace" && input.operation !== "edit") {
-        context.addIssue({
-            code: "custom",
-            path: ["result"],
-            message: "Only an image edit can replace a frame",
-        });
-    }
-    if (input.result === "new" && !input.name) {
-        context.addIssue({
-            code: "custom",
-            path: ["name"],
-            message: "A new generated frame requires a name",
-        });
-    }
-    if (input.result === "replace" && input.name) {
-        context.addIssue({
-            code: "custom",
-            path: ["name"],
-            message: "A replacement keeps the target frame name",
-        });
-    }
-    if (input.result === "replace" &&
-        (input.x !== undefined || input.y !== undefined)) {
-        context.addIssue({
-            code: "custom",
-            path: [input.x !== undefined ? "x" : "y"],
-            message: "A replacement keeps the target frame position",
-        });
-    }
-});
+};
+export const generateImageSchema = imageGenerationSchema(imageInputSchema);
+export const generateImageUrlSchema = imageGenerationSchema(imageUrlSchema);
+function imageGenerationSchema(input) {
+    return z.union([
+        z
+            .object({
+            ...imageGenerationBase,
+            operation: z.literal("generate"),
+            references: z.array(input).max(4).default([]),
+            ...newGeneratedFrame,
+        })
+            .strict(),
+        z
+            .object({
+            ...imageGenerationBase,
+            operation: z.literal("edit"),
+            target: designIdSchema,
+            references: z.array(input).max(3).default([]),
+            ...newGeneratedFrame,
+        })
+            .strict(),
+        z
+            .object({
+            ...imageGenerationBase,
+            operation: z.literal("edit"),
+            target: designIdSchema,
+            references: z.array(input).max(3).default([]),
+            result: z.literal("replace"),
+            name: z.never().optional(),
+            x: z.never().optional(),
+            y: z.never().optional(),
+        })
+            .strict(),
+    ]);
+}
 export const fileListSchema = z.object({
     paths: z.array(projectFilePathSchema),
 });
@@ -387,3 +371,10 @@ function isNormalizedQuaternion(value) {
         value.w * value.w;
     return Math.abs(squaredLength - 1) <= 1e-6;
 }
+function isFileName(value) {
+    return (value !== "." &&
+        value !== ".." &&
+        !value.includes("/") &&
+        !value.includes("\\") &&
+        !value.includes("\0"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawcall/design",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Typed API and remote CLI for Drawcall Design",
   "repository": {
     "type": "git",

package/skills/drawcall-design/SKILL.md

@@ -7,9 +7,11 @@ description: Create, modify, inspect, compose, and reuse 3D GLTS assets and opti
 
 ## CLI transport
 
-The CLI is the only Drawcall transport in this environment. Do not search for MCP tools or make direct HTTP requests. A failed CLI command does not justify switching transport.
+The commands below are the Drawcall transport in this environment. Use only this documented command interface. A failed command does not make the transport unavailable.
 
-CLI calls are shell command strings. Select the project with `-p <project-id>`. File commands take project-absolute paths that include the frame ID.
+Image frame creation and image-generation references accept public HTTP(S) URLs or local PNG, JPEG, and WebP files.
+
+Select the project with `-p <project-id>`. File commands take project-absolute paths that include the frame ID. Repeat `--reference` to preserve image-generation reference order.
 
 ```sh
 npx @drawcall/design project list
@@ -17,6 +19,8 @@ npx @drawcall/design -p r6z2n9k4x8m1qc frame list
 npx @drawcall/design -p r6z2n9k4x8m1qc ls
 npx @drawcall/design -p r6z2n9k4x8m1qc read /a4z8m2q7v9kcde/index.glts
 npx @drawcall/design -p r6z2n9k4x8m1qc edit /a4z8m2q7v9kcde/index.glts 'color: 0xffffff' 'color: 0x000000'
+npx @drawcall/design -p r6z2n9k4x8m1qc frame generate-image 'Product photograph' --prompt 'A product photograph of this object' --reference https://r6z2n9k4x8m1qc.design.drawcallcontent.com/a4z8m2q7v9kcde.webp
+npx @drawcall/design -p r6z2n9k4x8m1qc frame edit-image b4z8m2q7v9kcdf --prompt 'Use warmer light' --name 'Warm product photograph' --reference ./lighting.webp
 ```
 
 Design is a remote, current-state canvas. Inspect the project and its frames before changing them. Use immutable IDs for every project and frame target; names are only labels.
@@ -25,10 +29,14 @@ Design is a remote, current-state canvas. Inspect the project and its frames bef
 
 A project is a hosted filesystem at `https://<project-id>.design.drawcallcontent.com/`. Each frame owns one top-level directory, `/<frame-id>`. Files use project-absolute paths that include that directory, for example `/a4z8m2q7v9kcde/index.glts`.
 
-Create frames with an explicit type. Choose the type from the requested artifact, not from the word "frame": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image only for a supplied 2D image URL and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.
+Create frames with an explicit type. Choose the type from the requested artifact, not from the word "frame": use GLTS for a 3D object or scene, especially one another frame will reuse. Use image for an existing 2D image and Market only for an exact public asset reference, `name@version`. GLTS frames require a viewport size; image and Market frames derive their canvas size.
 
 Read a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. Only GLTS frame files may be created or deleted. Image and Market frame files are read-only.
 
+## Frame images
+
+Every frame has a public image at `https://<project-id>.design.drawcallcontent.com/<frame-id>.webp`. This URL represents the current rendered frame whether its type is GLTS, image, or Market. Pass it with `--reference` when one frame's appearance should inform another image. A reference may instead be a local PNG, JPEG, or WebP file.
+
 ## Failures
 
 An error means the requested operation did not happen. Follow its next action without switching transport. Correct invalid arguments from the documented shape. Refresh projects, frames, or files after a not-found or conflict error, then reuse the exact returned IDs and paths. Retry an upstream or internal failure once; if it repeats, report the failed operation and error. Never repeat an unchanged failed operation.
@@ -63,7 +71,7 @@ For a non-GLTS file from an image or Market frame, preserve the project filesyst
 const modelUrl = new URL("/market-frame-id/models/car.glb", import.meta.url);
 ```
 
-GLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support local helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.
+GLTS supports static `.glts`, `three`, Three addons, and bare npm imports. It does not support helper `.ts` modules, dynamic imports, cyclic GLTS graphs, or cross-asset inheritance. Keep the asset self-contained and compose with nested GLTS assets.
 
 The viewer uses the first camera found by depth-first traversal. If none exists, it autofits the asset. Put an authored camera in the scene only when its framing is intentional. Double-clicking a frame enters orbit from that resolved view; deselecting restores it.