@drawcall/design 0.9.1 → 0.10.0

package/dist/v1/schemas.d.ts

@@ -3,6 +3,7 @@ export declare const MAX_FRAME_DIMENSION = 4096;
 export declare const MAX_FILE_LENGTH = 512000;
 export declare const MAX_IMAGE_GENERATION_PROMPT_LENGTH = 2048;
 export declare const MAX_IMAGE_GENERATION_REFERENCES = 4;
+export declare const MAX_COMMENT_BODY_LENGTH = 10000;
 export declare const designIdSchema: z.ZodString;
 export declare const projectNameSchema: z.ZodString;
 export declare const projectBriefSchema: z.ZodString;
@@ -47,6 +48,119 @@ export declare const userSchema: z.ZodObject<{
     email: z.ZodString;
     image: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+export declare const commentBodySchema: z.ZodString;
+export declare const commentAuthorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    image: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const commentPositionInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"2d">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"3d">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    z: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export declare const commentPositionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"2d">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    frameContentRevision: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"3d">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    z: z.ZodNumber;
+    frameContentRevision: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export declare const commentReplySchema: z.ZodObject<{
+    id: z.ZodString;
+    commentId: z.ZodString;
+    body: z.ZodString;
+    author: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        image: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const commentResolutionSchema: z.ZodObject<{
+    resolvedAt: z.ZodString;
+    resolvedBy: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        image: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const commentSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    frameId: z.ZodString;
+    body: z.ZodString;
+    author: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        image: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    position: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"2d">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        frameContentRevision: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"3d">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+        frameContentRevision: z.ZodNumber;
+    }, z.core.$strict>], "kind">>;
+    replies: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        commentId: z.ZodString;
+        body: z.ZodString;
+        author: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            image: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>>;
+    resolution: z.ZodOptional<z.ZodObject<{
+        resolvedAt: z.ZodString;
+        resolvedBy: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            image: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const createCommentSchema: z.ZodUnion<readonly [z.ZodObject<{
+    project: z.ZodString;
+    frame: z.ZodString;
+    body: z.ZodString;
+    position: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"2d">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"3d">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    expectedContentRevision: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    project: z.ZodString;
+    frame: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strict>]>;
 export declare const projectSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -93,6 +207,20 @@ export declare const gltsFrameSchema: z.ZodObject<{
     }, z.core.$strict>>;
     contentRevision: z.ZodNumber;
 }, z.core.$strip>;
+export declare const markdownFrameSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    name: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    viewUrl: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    type: z.ZodLiteral<"markdown">;
+    contentRevision: z.ZodNumber;
+}, z.core.$strip>;
 export declare const imageGenerationOperationSchema: z.ZodEnum<{
     generate: "generate";
     edit: "edit";
@@ -144,6 +272,7 @@ export declare const imageFrameSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
     viewUrl: z.ZodString;
+    contentRevision: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     type: z.ZodLiteral<"image">;
@@ -181,6 +310,7 @@ export declare const marketFrameSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
     viewUrl: z.ZodString;
+    contentRevision: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     type: z.ZodLiteral<"market">;
@@ -223,6 +353,20 @@ export declare const frameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     viewUrl: z.ZodString;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
+    type: z.ZodLiteral<"markdown">;
+    contentRevision: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    name: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    viewUrl: z.ZodString;
+    contentRevision: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
     type: z.ZodLiteral<"image">;
     file: z.ZodString;
     provenance: z.ZodOptional<z.ZodObject<{
@@ -257,6 +401,7 @@ export declare const frameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
     viewUrl: z.ZodString;
+    contentRevision: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     type: z.ZodLiteral<"market">;
@@ -271,6 +416,15 @@ export declare const createGltsFrameSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
 }, z.core.$strict>;
+export declare const createMarkdownFrameSchema: z.ZodObject<{
+    project: z.ZodString;
+    name: z.ZodString;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"markdown">;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strict>;
 export declare const createImageFrameSchema: z.ZodObject<{
     project: z.ZodString;
     name: z.ZodString;
@@ -295,6 +449,14 @@ export declare const createFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"glts">;
     width: z.ZodNumber;
     height: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    project: z.ZodString;
+    name: z.ZodString;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"markdown">;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
 }, z.core.$strict>, z.ZodObject<{
     project: z.ZodString;
     name: z.ZodString;
@@ -377,7 +539,10 @@ export declare const textFileSchema: z.ZodObject<{
     type: z.ZodLiteral<"text">;
     path: z.ZodString;
     text: z.ZodString;
-    mediaType: z.ZodLiteral<"text/plain">;
+    mediaType: z.ZodEnum<{
+        "text/plain": "text/plain";
+        "text/markdown": "text/markdown";
+    }>;
 }, z.core.$strip>;
 export declare const binaryFileSchema: z.ZodObject<{
     type: z.ZodLiteral<"binary">;
@@ -389,7 +554,10 @@ export declare const fileSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
     path: z.ZodString;
     text: z.ZodString;
-    mediaType: z.ZodLiteral<"text/plain">;
+    mediaType: z.ZodEnum<{
+        "text/plain": "text/plain";
+        "text/markdown": "text/markdown";
+    }>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"binary">;
     path: z.ZodString;
@@ -424,6 +592,17 @@ export declare const gltsFrameExportSchema: z.ZodObject<{
         mediaType: z.ZodLiteral<"application/zip">;
     }, z.core.$strict>>;
 }, z.core.$strip>;
+export declare const markdownFrameExportSchema: z.ZodObject<{
+    frameId: z.ZodString;
+    frameName: z.ZodString;
+    projectId: z.ZodString;
+    type: z.ZodLiteral<"markdown">;
+    source: z.ZodNullable<z.ZodObject<{
+        filename: z.ZodString;
+        url: z.ZodString;
+        mediaType: z.ZodLiteral<"text/markdown">;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
 export declare const imageFrameExportSchema: z.ZodObject<{
     frameId: z.ZodString;
     frameName: z.ZodString;
@@ -469,6 +648,16 @@ export declare const frameExportSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         url: z.ZodString;
         mediaType: z.ZodLiteral<"application/zip">;
     }, z.core.$strict>>;
+}, z.core.$strip>, z.ZodObject<{
+    frameId: z.ZodString;
+    frameName: z.ZodString;
+    projectId: z.ZodString;
+    type: z.ZodLiteral<"markdown">;
+    source: z.ZodNullable<z.ZodObject<{
+        filename: z.ZodString;
+        url: z.ZodString;
+        mediaType: z.ZodLiteral<"text/markdown">;
+    }, z.core.$strict>>;
 }, z.core.$strip>, z.ZodObject<{
     frameId: z.ZodString;
     frameName: z.ZodString;
@@ -496,11 +685,19 @@ export declare const frameExportSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strip>], "type">;
 export type User = z.infer<typeof userSchema>;
+export type CommentAuthor = z.infer<typeof commentAuthorSchema>;
+export type CommentPositionInput = z.infer<typeof commentPositionInputSchema>;
+export type CommentPosition = z.infer<typeof commentPositionSchema>;
+export type CommentReply = z.infer<typeof commentReplySchema>;
+export type CommentResolution = z.infer<typeof commentResolutionSchema>;
+export type Comment = z.infer<typeof commentSchema>;
+export type CreateComment = z.infer<typeof createCommentSchema>;
 export type Project = z.infer<typeof projectSchema>;
 export type CreateProjectFromBrief = z.infer<typeof createProjectFromBriefSchema>;
 export type ProjectDerivationStatus = z.infer<typeof projectDerivationStatusSchema>;
 export type CameraPose = z.infer<typeof cameraPoseSchema>;
 export type GltsFrame = z.infer<typeof gltsFrameSchema>;
+export type MarkdownFrame = z.infer<typeof markdownFrameSchema>;
 export type ImageFrame = z.infer<typeof imageFrameSchema>;
 export type ImageGenerationOperation = z.infer<typeof imageGenerationOperationSchema>;
 export type ImageGenerationResult = z.infer<typeof imageGenerationResultSchema>;
@@ -510,6 +707,7 @@ export type ImageInputProvenance = z.infer<typeof imageInputProvenanceSchema>;
 export type MarketFrame = z.infer<typeof marketFrameSchema>;
 export type Frame = z.infer<typeof frameSchema>;
 export type CreateGltsFrame = z.infer<typeof createGltsFrameSchema>;
+export type CreateMarkdownFrame = z.infer<typeof createMarkdownFrameSchema>;
 export type CreateImageFrame = z.infer<typeof createImageFrameSchema>;
 export type CreateMarketFrame = z.infer<typeof createMarketFrameSchema>;
 export type CreateFrame = z.infer<typeof createFrameSchema>;
@@ -522,6 +720,7 @@ export type DesignFile = z.infer<typeof fileSchema>;
 export type FileMutation = z.infer<typeof fileMutationSchema>;
 export type Screenshot = z.infer<typeof screenshotSchema>;
 export type GltsFrameExport = z.infer<typeof gltsFrameExportSchema>;
+export type MarkdownFrameExport = z.infer<typeof markdownFrameExportSchema>;
 export type ImageFrameExport = z.infer<typeof imageFrameExportSchema>;
 export type MarketFrameExport = z.infer<typeof marketFrameExportSchema>;
 export type FrameExport = z.infer<typeof frameExportSchema>;

package/dist/v1/schemas.js

@@ -3,6 +3,7 @@ export const MAX_FRAME_DIMENSION = 4_096;
 export const MAX_FILE_LENGTH = 512_000;
 export const MAX_IMAGE_GENERATION_PROMPT_LENGTH = 2_048;
 export const MAX_IMAGE_GENERATION_REFERENCES = 4;
+export const MAX_COMMENT_BODY_LENGTH = 10_000;
 export const designIdSchema = z
     .string()
     .regex(/^[a-z0-9]{14}$/, "IDs are exactly 14 lowercase alphanumeric characters; use an ID returned by a list operation");
@@ -93,6 +94,89 @@ export const userSchema = z.object({
     email: z.string().email(),
     image: z.string().url().nullable(),
 });
+export const commentBodySchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(MAX_COMMENT_BODY_LENGTH);
+export const commentAuthorSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    image: z.string().url().nullable(),
+})
+    .strict();
+const commentCoordinateSchema = z.number().finite();
+const normalizedCommentCoordinateSchema = commentCoordinateSchema.min(0).max(1);
+export const commentPositionInputSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("2d"),
+        x: normalizedCommentCoordinateSchema,
+        y: normalizedCommentCoordinateSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("3d"),
+        x: commentCoordinateSchema,
+        y: commentCoordinateSchema,
+        z: commentCoordinateSchema,
+    })
+        .strict(),
+]);
+export const commentPositionSchema = z.discriminatedUnion("kind", [
+    commentPositionInputSchema.options[0].extend({
+        frameContentRevision: z.number().int().nonnegative(),
+    }),
+    commentPositionInputSchema.options[1].extend({
+        frameContentRevision: z.number().int().nonnegative(),
+    }),
+]);
+export const commentReplySchema = z
+    .object({
+    id: designIdSchema,
+    commentId: designIdSchema,
+    body: commentBodySchema,
+    author: commentAuthorSchema,
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
+export const commentResolutionSchema = z
+    .object({
+    resolvedAt: z.string().datetime(),
+    resolvedBy: commentAuthorSchema,
+})
+    .strict();
+export const commentSchema = z
+    .object({
+    id: designIdSchema,
+    projectId: designIdSchema,
+    frameId: designIdSchema,
+    body: commentBodySchema,
+    author: commentAuthorSchema,
+    position: commentPositionSchema.optional(),
+    replies: z.array(commentReplySchema),
+    resolution: commentResolutionSchema.optional(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
+const createCommentBaseSchema = z.object({
+    project: designIdSchema,
+    frame: designIdSchema,
+    body: commentBodySchema,
+});
+export const createCommentSchema = z.union([
+    createCommentBaseSchema
+        .extend({
+        position: commentPositionInputSchema,
+        expectedContentRevision: z.number().int().nonnegative(),
+    })
+        .strict(),
+    createCommentBaseSchema.strict(),
+]);
 export const projectSchema = z.object({
     id: designIdSchema,
     name: projectNameSchema,
@@ -116,6 +200,7 @@ const frameBaseSchema = z.object({
     width: frameSizeSchema,
     height: frameSizeSchema,
     viewUrl: httpUrlSchema,
+    contentRevision: z.number().int().nonnegative().optional(),
     createdAt: z.string().datetime(),
     updatedAt: z.string().datetime(),
 });
@@ -124,6 +209,10 @@ export const gltsFrameSchema = frameBaseSchema.extend({
     camera: cameraPoseSchema.optional(),
     contentRevision: z.number().int().nonnegative(),
 });
+export const markdownFrameSchema = frameBaseSchema.extend({
+    type: z.literal("markdown"),
+    contentRevision: z.number().int().nonnegative(),
+});
 export const imageGenerationOperationSchema = z.enum(["generate", "edit"]);
 export const imageGenerationResultSchema = z.enum(["new", "replace"]);
 const imageGenerationDigestSchema = z
@@ -176,6 +265,7 @@ export const marketFrameSchema = frameBaseSchema.extend({
 });
 export const frameSchema = z.discriminatedUnion("type", [
     gltsFrameSchema,
+    markdownFrameSchema,
     imageFrameSchema,
     marketFrameSchema,
 ]);
@@ -192,6 +282,13 @@ export const createGltsFrameSchema = createFrameBaseSchema
     height: frameSizeSchema,
 })
     .strict();
+export const createMarkdownFrameSchema = createFrameBaseSchema
+    .extend({
+    type: z.literal("markdown"),
+    width: frameSizeSchema,
+    height: frameSizeSchema,
+})
+    .strict();
 export const createImageFrameSchema = createFrameBaseSchema
     .extend({
     type: z.literal("image"),
@@ -206,6 +303,7 @@ export const createMarketFrameSchema = createFrameBaseSchema
     .strict();
 export const createFrameSchema = z.discriminatedUnion("type", [
     createGltsFrameSchema,
+    createMarkdownFrameSchema,
     createImageFrameSchema,
     createMarketFrameSchema,
 ]);
@@ -266,7 +364,7 @@ export const textFileSchema = z.object({
     type: z.literal("text"),
     path: projectFilePathSchema,
     text: z.string(),
-    mediaType: z.literal("text/plain"),
+    mediaType: z.enum(["text/plain", "text/markdown"]),
 });
 export const binaryFileSchema = z.object({
     type: z.literal("binary"),
@@ -319,6 +417,12 @@ export const gltsFrameExportSchema = frameExportBaseSchema.extend({
         .extend({ mediaType: z.literal("application/zip") })
         .nullable(),
 });
+export const markdownFrameExportSchema = frameExportBaseSchema.extend({
+    type: z.literal("markdown"),
+    source: frameDownloadSchema
+        .extend({ mediaType: z.literal("text/markdown") })
+        .nullable(),
+});
 export const imageFrameExportSchema = frameExportBaseSchema.extend({
     type: z.literal("image"),
     download: frameDownloadSchema.extend({
@@ -332,6 +436,7 @@ export const marketFrameExportSchema = frameExportBaseSchema.extend({
 });
 export const frameExportSchema = z.discriminatedUnion("type", [
     gltsFrameExportSchema,
+    markdownFrameExportSchema,
     imageFrameExportSchema,
     marketFrameExportSchema,
 ]);

package/package.json

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

package/skills/drawcall-design/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: drawcall-design
-description: Create, modify, inspect, compose, and reuse 3D GLTS assets and optional image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, or GLTS assets. Do not use for full games, applications, or unrelated image generation.
+description: Create, modify, inspect, compose, and reuse GLTS scenes, Markdown documents, and image or Market references in Drawcall Design. Use whenever the user names Drawcall Design or one of its projects, canvases, frames, filesystems, GLTS assets, or Markdown frames. Do not use for full games, applications, or unrelated image generation.
 ---
 
 # Drawcall Design
 
 ## CLI 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.
+The commands below are the Drawcall transport in this environment. For Design operations, use only this documented command interface. A failed command does not make the transport unavailable.
 
 Image frame creation and image-generation references accept public HTTP(S) URLs or local PNG, JPEG, and WebP files.
 
@@ -19,23 +19,51 @@ 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 comment list a4z8m2q7v9kcde
+npx drawcall design -p r6z2n9k4x8m1qc comment show c4z8m2q7v9kcdf
+npx drawcall design -p r6z2n9k4x8m1qc comment create a4z8m2q7v9kcde 'The bevel catches the key light here.' --position-3d 0.2,1.1,-0.4
+npx drawcall design -p r6z2n9k4x8m1qc comment reply c4z8m2q7v9kcdf 'Adjusted the material roughness.'
+npx drawcall design -p r6z2n9k4x8m1qc comment resolve c4z8m2q7v9kcdf
+npx drawcall design -p r6z2n9k4x8m1qc comment delete c4z8m2q7v9kcdf --yes
 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.
+Comment create and reply text is positional to keep commands compact. Omit it or pass `-` to read the text from stdin. Use `--position-2d x,y` only for normalized image coordinates and `--position-3d x,y,z` only for authoritative GLTS world coordinates.
+
+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 mutable labels. In user-facing replies, refer to projects, frames, and other named resources by their current names. Do not expose their IDs unless the user explicitly asks for them; IDs may remain embedded in URLs that link to those resources.
+
+We recommend using Drawcall Market when a design needs 3D assets such as models, textures, or environments.
 
 ## Project filesystem
 
 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 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.
+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, Markdown for a formatted text document, image for an existing 2D image, and Market only for an exact public asset reference, `name@version`. GLTS and Markdown 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.
+Read a file before editing it. Use a narrow edit for one known change and write a complete file when replacing it. GLTS and Markdown 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.
+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, Markdown, 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.
+
+## Markdown documents
+
+A Markdown frame contains one optional source file at `/<frame-id>/index.md`; without it the frame renders as an empty document. Raw HTML is not rendered. Use ordinary Markdown image syntax with a frame's canonical WebP path to embed its current rendering:
+
+```md
+![Descriptive alternative text](/other-frame-id.webp)
+```
+
+An absolute canonical WebP URL from the same project is equivalent. A Markdown document may embed up to 32 existing GLTS, image, or Market frames. It may not embed itself or another Markdown frame. Use the canonical syntax instead of copying a screenshot URL or source asset so the document follows later frame changes.
+
+## Comments and annotations
+
+Use comments for review conversations and persistent annotations, including explanations of objects or regions inside 2D and 3D frames. Inspect the current comments before replying, resolving, reopening, or deleting so the action targets the current thread.
+
+A comment without a position applies to its frame. A 2D position is normalized image space and applies only to an image frame. A 3D position is GLTS world space and applies only to a GLTS frame. Add a position only when its coordinates are authoritative; never infer 3D depth from a screenshot. Prefer a frame-level comment when the precise position is unknown.
+
+Positioned comments retain the frame version on which they were placed. If the frame later changes, treat the position as potentially stale and re-inspect the frame before relying on it. Replies belong to the root comment's thread. Resolved threads do not accept replies, so reopen one before continuing it. Resolve a thread when its concern has been addressed. Delete a comment or reply only when explicitly requested because deletion is permanent; deleting a root also deletes its replies. Comment authors come from the authenticated Drawcall account—never invent an author identity.
 
 ## Failures
 
@@ -71,8 +99,43 @@ 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);
 ```
 
+When a `.glts` constructor starts resource loading through a Three.js loader, import the current runtime's manager and pass it to that loader. This makes the initial root `loadAsync()` promise or `load()` callback wait for the resource and surface its failure. Use it with `TextureLoader`, `GLTFLoader`, `FileLoader`, and comparable loaders. Reload construction remains synchronous, and arbitrary asynchronous work is not tracked.
+
+```ts
+import * as THREE from "three";
+import { loadingManager } from "@drawcall/glts";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+
+export default class Car extends THREE.Group {
+  constructor() {
+    super();
+    new GLTFLoader(loadingManager).load(
+      new URL("./car.glb", import.meta.url).href,
+      ({ scene }) => this.add(scene),
+    );
+  }
+}
+```
+
 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.
+Keep preview-only camera and lighting out of the default scene so importing the GLTS composes only reusable content. A root `index.glts` may export `previewCamera` and `previewLighting`; these named exports affect its direct preview and are ignored when another GLTS imports it. `previewLighting` must be a `THREE.Object3D` containing at least one light.
+
+```ts
+import * as THREE from "three";
+
+export const previewCamera = new THREE.PerspectiveCamera(40, 1, 0.1, 100);
+previewCamera.position.set(4, 3, 6);
+previewCamera.lookAt(0, 0, 0);
+
+export const previewLighting = new THREE.Group();
+previewLighting.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));
+
+export default class Product extends THREE.Group {
+  // Reusable scene content only.
+}
+```
+
+When `previewCamera` is absent, the viewer uses the first camera found by depth-first traversal, then autofits if the scene has none. A saved frame camera remains the user override. Double-clicking a frame enters orbit from the resolved view; deselecting restores it.
 
 Treat authoritative source or structured state as sufficient when it directly and completely determines the requested property. Do not take a screenshot merely to reconfirm that evidence. Take one only when the result depends on rendering or visual relationships the source cannot establish, such as layout, overlap, clipping, camera framing, lighting, or runtime-generated appearance, or when the user explicitly asks. Then inspect it against the request and iterate until the evidence supports completion.