@pinepaper.studio/mcp-server 1.6.19 → 1.6.21

package/dist/tools/handlers.js

@@ -5,8 +5,9 @@
  * Supports i18n for localized error and success messages.
  * Supports browser execution via Puppeteer.
  */
+import { CRAFT_FRAME_JS, generateDrawWeave, generateDrawKnots, generateDrawSashiko, generateDrawSubdivision, generateUiKit, uiKitCallProblems, } from './craft-tools.js';
 import { codeGenerator, generateQueryMutationsCode, SHEET_RUBRIC } from '../types/code-generator.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ChoreographInputSchema, EmitterInputSchema, MorphSequenceInputSchema, OriginalCharacterInputSchema, LookInputSchema, RenderHookInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
@@ -27,8 +28,11 @@ ImportImageInputSchema,
 // Scene management schemas
 ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
 // New consolidated tool schemas
-SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, PlaceOnSurfaceInputSchema, StyledSceneInputSchema, ErrorCodes, } from '../types/schemas.js';
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, HandDrawnInputSchema, PenFigureInputSchema, CreateCharacterInputSchema, CharacterActionInputSchema, CharacterPoseInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, PlaceOnSurfaceInputSchema, DrawWeaveInputSchema, DrawKnotsInputSchema, DrawSashikoInputSchema, DrawSubdivisionInputSchema, UiKitInputSchema, StyledSceneInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError, z } from 'zod';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { effectClass } from './effect-class.js';
+import { EFFECT_BEFORE_JS, effectAfterJs, namedItemIds, idMayBeGone, NO_CHANGE_NOTE } from './effect-check.js';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, extname } from 'node:path';
@@ -624,6 +628,17 @@ function dataResult(value) {
  * index.ts adds toolMs, the whole call, for every tool.
  */
 export const TIMING_META_KEY = 'pinepaper.studio/timing';
+export const EFFECT_META_KEY = 'pinepaper.studio/effect';
+/** The tool and action of the call in flight, for executeOrGenerate's effect check. */
+const callContext = new AsyncLocalStorage();
+let READ_ONLY_TOOLS = null;
+async function readOnlyTools() {
+    if (!READ_ONLY_TOOLS) {
+        const { PINEPAPER_TOOLS } = await import('./definitions.js');
+        READ_ONLY_TOOLS = new Set(PINEPAPER_TOOLS.filter((t) => t.annotations?.readOnlyHint).map((t) => t.name));
+    }
+    return READ_ONLY_TOOLS;
+}
 export function withTiming(out, t) {
     const meta = (out._meta ?? {});
     const prev = (meta[TIMING_META_KEY] ?? {});
@@ -844,6 +859,80 @@ const REMOVE_ITEMS_CREATED_SINCE_MARK = `(function () {
  * false when the page could not be marked (the rollback is then skipped and
  * the failure note says nothing about the scene it cannot vouch for).
  */
+/**
+ * The studio's job gate (FxTool D92). PinePaperAgent.startJob is the one place
+ * a stale studio reloads, and only when the job is about to clear the canvas:
+ * it resolves {reloading: true, fromBuild, toBuild} and the PAGE reloads, so
+ * nothing running in it survives — the wait has to happen here. Poll the new
+ * page through waitForReady, open the job again, then let start_job's own
+ * setup (clear, canvas size) run on the fresh page.
+ */
+export async function studioJobGate(input, options, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    const mode = options.executionMode ?? getExecutionMode();
+    if (mode === 'code' || !options.executeInBrowser || options.deferred)
+        return {};
+    const controller = options.browserController || getBrowserController();
+    if (!controller.connected) {
+        try {
+            await controller.connect();
+        }
+        catch {
+            return {};
+        }
+    }
+    const args = JSON.stringify({ ...(input.name ? { name: input.name } : {}), clearCanvas: input.clearCanvas !== false });
+    const START = `(async function () {
+  const A = typeof window !== 'undefined' ? window.PinePaperAgent : null;
+  if (!A || !A.startJob) return { legacy: true };
+  return await A.startJob(${args});
+})();`;
+    const call = async (code) => {
+        try {
+            const r = await controller.executeCode(code, false, { bypassGovernor: true });
+            return r.success ? r.result : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const first = await call(START);
+    if (!first || first.legacy || (first.jobOpen === undefined && first.reloading === undefined))
+        return {};
+    const build = (j) => ({ buildId: j.buildId, liveBuildId: j.liveBuildId, stale: !!j.stale });
+    if (first.reloading) {
+        const READY = `(async function () {
+  const A = typeof window !== 'undefined' ? window.PinePaperAgent : null;
+  if (!A || !A.waitForReady) return { ready: false };
+  await A.waitForReady();
+  return { ready: true };
+})();`;
+        let ready = false;
+        for (let i = 0; i < 60 && !ready; i++) { // ~30 s: a reload is ~100 ms plus a fresh boot
+            await wait(500);
+            const r = await call(READY);
+            ready = !!(r && r.ready);
+        }
+        if (!ready)
+            return { warning: `the studio was reloading from build ${first.fromBuild} to ${first.toBuild} and did not come back within 30 s; this job may run on the old page.`, build: build(first) };
+        const second = await call(START);
+        if (!second)
+            return { warning: 'the studio reloaded but did not open the job again.', build: build(first) };
+        return {
+            note: `Studio was on build ${first.fromBuild}, reloaded to ${first.toBuild} before this job.`,
+            ...(second.stale ? { warning: `the studio is still on an old build after reloading (${second.buildId}; live ${second.liveBuildId})${second.reason ? ': ' + second.reason : ''}.` } : {}),
+            build: build(second),
+        };
+    }
+    if (first.stale) {
+        return {
+            warning: input.clearCanvas === false
+                ? `studio is on old build ${first.buildId} (live: ${first.liveBuildId}); finish, then start a new job to update.`
+                : `studio is on old build ${first.buildId} (live: ${first.liveBuildId}) and was not reloaded${first.reason ? ': ' + first.reason : ''}.`,
+            build: build(first),
+        };
+    }
+    return { build: build(first) };
+}
 async function markItemsBeforeRun(controller) {
     try {
         const r = await controller.executeCode(MARK_ITEMS_BEFORE_RUN, false, { bypassGovernor: true });
@@ -1011,6 +1100,24 @@ async function captureSheet(input, options) {
             }],
     };
 }
+/**
+ * The canvas the craft tools fill when the call gives no bounds. Asked of the
+ * studio, so a portrait or square canvas is filled rather than a 1280x720
+ * corner of it; undefined (the generators' own default) without a studio.
+ */
+async function craftFrame(options) {
+    const ctl = options.browserController;
+    if (!options.executeInBrowser || !ctl || !ctl.connected)
+        return undefined;
+    try {
+        const r = await ctl.executeCode(CRAFT_FRAME_JS, false);
+        const f = r.success ? r.result : null;
+        return f && f.width > 0 && f.height > 0 ? f : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function executeOrGenerate(code, description, options, toolName, 
 /**
  * Values too large to live inside the generated code. Written to
@@ -1156,6 +1263,23 @@ ${code}
     const rollbackOnFailure = toolName === 'pinepaper_execute_custom_code'
         && await markItemsBeforeRun(controller);
     const governorTimeoutMs = LONG_GOVERNOR_BUDGET_MS[toolName];
+    // NO SILENT SUCCESS (effect-class.ts / effect-check.ts): fingerprint a
+    // mutating call before and after it runs.
+    const ctx = callContext.getStore();
+    const action = ctx && ctx.toolName === toolName ? ctx.action : undefined;
+    const effect = effectClass(toolName, action, (await readOnlyTools()).has(toolName));
+    const checkEffect = effect === 'mutates' && !rollbackOnFailure;
+    let effectCheckMs = 0;
+    let effectArmed = false;
+    if (checkEffect) {
+        const t0 = Date.now();
+        try {
+            const r = await controller.executeCode(EFFECT_BEFORE_JS, false, { bypassGovernor: true });
+            effectArmed = !!(r.success && r.result?.ok);
+        }
+        catch { /* unchecked this time */ }
+        effectCheckMs += Date.now() - t0;
+    }
     const result = await controller.executeCode(code, shouldTakeScreenshot, {
         ...(stage ? { stage } : {}),
         ...(governorTimeoutMs ? { governorTimeoutMs } : {}),
@@ -1226,7 +1350,15 @@ ${code}
     const inner = innerVerdict;
     if (inner) {
         const canvasState = await captureCanvasState(controller);
-        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
+        // THE ENGINE'S OWN REASON, when it gave one. An emitter's refusal is often
+        // generic ("the studio refused the time_expression relation") while the
+        // engine said exactly why in a warning the governor captured ("unknown
+        // property 'opacty' — did you mean 'opacity'?"; D78). Production strips
+        // console.warn, so this is the only place the model can read it.
+        const said = (Array.isArray(result.report?.warnings) ? result.report.warnings : [])
+            .filter((w) => typeof w === 'string' && w.length > 0 && !inner.includes(w))
+            .slice(0, 3);
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, said.length ? `${inner} The studio said: ${said.join(' | ')}` : inner, {
             code, result: result.result, governorReport: result.report,
             ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
         }, { toolName, canvasState: canvasState || undefined }), timing);
@@ -1240,7 +1372,32 @@ ${code}
         }
         catch { /* no session */ }
     }
-    return withTiming(withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result), timing);
+    let noChangeNote = null;
+    let effectMeta = null;
+    if (checkEffect && effectArmed) {
+        const t0 = Date.now();
+        const ids = idMayBeGone(toolName, action) ? [] : namedItemIds(result.result);
+        const verdict = await controller.executeCode(effectAfterJs(ids), false, { bypassGovernor: true })
+            .then((r) => (r.success ? r.result : null))
+            .catch(() => null);
+        effectCheckMs += Date.now() - t0;
+        if (verdict && verdict.ok) {
+            // A CONTRADICTION, not idempotence: the call names an item that is not there.
+            if (verdict.missing && verdict.missing.length) {
+                return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, `the call reported ${verdict.missing.join(', ')}, which ${verdict.missing.length === 1 ? 'is' : 'are'} not on the canvas: it did not make what it said it made.`, { result: result.result }, { toolName }), { ...timing, effectCheckMs });
+            }
+            const changed = verdict.changed ?? [];
+            effectMeta = { class: effect, changed: changed.length > 0, signals: changed, checked: verdict.checked ?? [] };
+            if (!changed.length)
+                noChangeNote = NO_CHANGE_NOTE(verdict.checked ?? []);
+        }
+    }
+    let out = withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result);
+    if (noChangeNote)
+        out = { ...out, content: [...(out.content ?? []), { type: 'text', text: noChangeNote }] };
+    if (effectMeta)
+        out = { ...out, _meta: { ...(out._meta ?? {}), [EFFECT_META_KEY]: effectMeta } };
+    return withTiming(out, checkEffect ? { ...timing, effectCheckMs } : timing);
 }
 /**
  * The emitted code's own verdict, when it reported one and it was a failure.
@@ -1429,7 +1586,7 @@ export function ignoredArgumentsNote(toolName, args) {
 export async function handleToolCall(toolName, args, options = {}) {
     const tracker = getPerformanceTracker();
     const baseTimerId = `${toolName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-    const result = await handleToolCallInner(toolName, args, options, tracker, baseTimerId);
+    const result = await callContext.run({ toolName, action: typeof args.action === 'string' ? args.action : undefined }, () => handleToolCallInner(toolName, args, options, tracker, baseTimerId));
     const ignoredNote = ignoredArgumentsNote(toolName, args);
     if (ignoredNote)
         result.content = [...(result.content ?? []), { type: 'text', text: ignoredNote }];
@@ -1650,6 +1807,17 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateDeform(input);
                 return executeOrGenerate(code, `Deform: ${input.action}`, options, 'pinepaper_deform');
             }
+            case 'pinepaper_hand_drawn': {
+                const input = HandDrawnInputSchema.parse(args);
+                const code = codeGenerator.generateHandDrawn(input);
+                return executeOrGenerate(code, `Hand-drawn style: ${input.style ?? input.mode ?? 'sketchy'}`, options, 'pinepaper_hand_drawn');
+            }
+            case 'pinepaper_pen_figure': {
+                const input = PenFigureInputSchema.parse(args);
+                const code = codeGenerator.generatePenFigure(input);
+                const what = input.action === 'list' ? 'List the pen figures' : `Draw ${typeof input.figure === 'string' ? input.figure : 'a figure'} with a pen`;
+                return executeOrGenerate(code, what, options, 'pinepaper_pen_figure');
+            }
             case 'pinepaper_sprite_sheet': {
                 const input = SpriteSheetInputSchema.parse(args);
                 const code = codeGenerator.generateSpriteSheet(input);
@@ -1718,6 +1886,60 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const description = `Places ${input.concept} as ${plan.parts.length} parts with ${plan.tracks} keyframe tracks`;
                 return executeOrGenerate(code, description, options, 'pinepaper_character');
             }
+            case 'pinepaper_create_character': {
+                const input = CreateCharacterInputSchema.parse(args);
+                // If layered bundle provided, use importLayeredCharacter
+                if (input.bundle) {
+                    const bundleInfo = input.bundle.info || input.bundle;
+                    const bundleImages = input.bundle.images || {};
+                    const code = codeGenerator.generateImportLayeredCharacter({ info: bundleInfo, images: bundleImages });
+                    return executeOrGenerate(code, `Import layered character: ${input.name || input.characterId || 'bundle'}`, options, 'pinepaper_create_character');
+                }
+                // If concept/preset matches a planCharacter concept, plan it
+                const conceptName = input.concept || input.preset;
+                if (conceptName) {
+                    const formattedConcept = conceptName.startsWith('pp:') ? conceptName : `pp:${conceptName.charAt(0).toUpperCase() + conceptName.slice(1)}`;
+                    const plan = planCharacter({
+                        concept: formattedConcept,
+                        at: { x: input.x, y: input.y },
+                        scale: input.scale,
+                    });
+                    if (plan.ok) {
+                        const code = generateCharacterCode(plan, {
+                            generateCreateItem: (i) => codeGenerator.generateCreateItem(i),
+                            generateKeyframeAnimate: (i) => codeGenerator.generateKeyframeAnimate(i),
+                        }, {
+                            createItem: (a) => CreateItemInputSchema.parse(a),
+                            keyframeAnimate: (a) => KeyframeAnimateInputSchema.parse(a),
+                        });
+                        return executeOrGenerate(code, `Places character ${formattedConcept}`, options, 'pinepaper_create_character');
+                    }
+                }
+                const code = codeGenerator.generateCreateCharacter(input);
+                return executeOrGenerate(code, `Create character: ${input.name || input.characterId || 'Character'}`, options, 'pinepaper_create_character');
+            }
+            case 'pinepaper_character_action': {
+                const input = CharacterActionInputSchema.parse(args);
+                const act = String(input.action || 'walk').toLowerCase();
+                const FACES = ['blink', 'frown', 'smile', 'surprise', 'talk', 'wink'];
+                if (FACES.includes(act)) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `"${act}" is a facial expression — use pinepaper_character_pose with { expression: "${act}" }. Actions: walk, run, locomotion, wave, dance, jump, idle`,
+                            }],
+                        isError: true,
+                    };
+                }
+                const code = codeGenerator.generateCharacterAction(input);
+                return executeOrGenerate(code, `Character action: ${act}`, options, 'pinepaper_character_action');
+            }
+            case 'pinepaper_character_pose': {
+                const input = CharacterPoseInputSchema.parse(args);
+                const expr = String(input.expression || 'smile').toLowerCase();
+                const code = codeGenerator.generateCharacterPose(input);
+                return executeOrGenerate(code, `Character pose/expression: ${expr}`, options, 'pinepaper_character_pose');
+            }
             case 'pinepaper_batch_create': {
                 const input = BatchCreateInputSchema.parse(args);
                 const code = codeGenerator.generateBatchCreate(input);
@@ -1887,6 +2109,30 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 return executeOrGenerate(code, `Text effect: ${input.action}`, options, 'pinepaper_text_effect');
             }
             // ─── 1.6.4: agent surface for the Tier-2 engine features ───
+            case 'pinepaper_look': {
+                const input = LookInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateLook(input), `Look: ${input.action}`, options, 'pinepaper_look');
+            }
+            case 'pinepaper_original_character': {
+                const input = OriginalCharacterInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateOriginalCharacter(input), `Original character: ${input.action}`, options, 'pinepaper_original_character');
+            }
+            case 'pinepaper_morph_sequence': {
+                const input = MorphSequenceInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateMorphSequence(input), `Morph sequence: ${input.states.length} states`, options, 'pinepaper_morph_sequence');
+            }
+            case 'pinepaper_emitter': {
+                const input = EmitterInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateEmitter(input), `Emitter: ${input.action}`, options, 'pinepaper_emitter');
+            }
+            case 'pinepaper_render_hook': {
+                const input = RenderHookInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateRenderHook(input), `Render hook: ${input.action}`, options, 'pinepaper_render_hook');
+            }
+            case 'pinepaper_choreograph': {
+                const input = ChoreographInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateChoreograph(input), `Choreograph: ${input.beats.map((b) => b.verb).join(' → ')}`, options, 'pinepaper_choreograph');
+            }
             case 'pinepaper_relight': {
                 const input = RelightInputSchema.parse(args);
                 return executeOrGenerate(codeGenerator.generateRelight(input), `Relight: ${input.action}`, options, 'pinepaper_relight');
@@ -1899,6 +2145,44 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const input = StyledSceneInputSchema.parse(args);
                 return executeOrGenerate(codeGenerator.generateStyledScene(input), `Styled scene${input.style ? `: ${input.style}` : ''}`, options, 'pinepaper_styled_scene');
             }
+            // The cloud's craft tools, shared (craft-tools.ts says what differs locally).
+            case 'pinepaper_draw_weave': {
+                const input = DrawWeaveInputSchema.parse(args);
+                const code = generateDrawWeave(input, await craftFrame(options));
+                return executeOrGenerate(code, `Draw a ${input.weave ?? 'plain'} weave`, options, 'pinepaper_draw_weave');
+            }
+            case 'pinepaper_draw_knots': {
+                const input = DrawKnotsInputSchema.parse(args);
+                if (!input.points?.length) {
+                    return {
+                        content: [{ type: 'text', text: 'pinepaper_draw_knots: give points — [{x, y}, …], one per knot. The tool places knots where you say and draws nothing without them.' }],
+                        isError: true,
+                    };
+                }
+                return executeOrGenerate(generateDrawKnots(input), `Draw ${input.points.length} embroidered knot(s)`, options, 'pinepaper_draw_knots');
+            }
+            case 'pinepaper_draw_sashiko': {
+                const input = DrawSashikoInputSchema.parse(args);
+                const code = generateDrawSashiko(input, await craftFrame(options));
+                return executeOrGenerate(code, `Draw ${input.pattern ?? 'seigaiha'} sashiko`, options, 'pinepaper_draw_sashiko');
+            }
+            case 'pinepaper_draw_subdivision': {
+                const input = DrawSubdivisionInputSchema.parse(args);
+                const code = generateDrawSubdivision(input, await craftFrame(options));
+                return executeOrGenerate(code, `Draw a ${input.preset ?? 'mondrian'} subdivision`, options, 'pinepaper_draw_subdivision');
+            }
+            case 'pinepaper_ui_kit': {
+                const input = UiKitInputSchema.parse(args);
+                const problems = uiKitCallProblems(input);
+                const code = problems.length ? null : generateUiKit(input);
+                if (!code) {
+                    return {
+                        content: [{ type: 'text', text: `pinepaper_ui_kit: ${problems.join(' ') || 'nothing to draw'}` }],
+                        isError: true,
+                    };
+                }
+                return executeOrGenerate(code, `UI kit: ${input.action}`, options, 'pinepaper_ui_kit');
+            }
             case 'pinepaper_place_on_surface': {
                 const input = PlaceOnSurfaceInputSchema.parse(args);
                 const code = codeGenerator.generatePlaceOnSurface(input);
@@ -2179,7 +2463,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const description = getLocalizedSuccessMessage(i18n, 'relationAdded', {
                     relationType: input.relationType ?? `preset:${input.presetId}`,
                     sourceId: input.sourceId,
-                    targetId: input.targetId || 'self',
+                    targetId: input.targetId || '(no target)',
                 });
                 return executeOrGenerate(code, description, options, 'pinepaper_add_relation');
             }
@@ -3130,11 +3414,20 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 }
                 const code = codeGenerator.generateAgentStartJob(input);
                 const descriptionText = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
+                // A STALE STUDIO IS RELOADED HERE, AND ONLY HERE (D92): the canvas is
+                // about to be cleared anyway. The setup below runs on the new page.
+                const gate = await studioJobGate(input, options);
                 const result = await executeOrGenerate(code, descriptionText, options, 'pinepaper_agent_start_job');
                 // Append a 1-line workflow hint
                 if (result.content && result.content.length > 0 && result.content[0].type === 'text') {
                     result.content[0].text += `\n\nNEXT: Call batch_execute with all operations, then end_job.`;
+                    if (gate.note)
+                        result.content[0].text = `${gate.note}\n\n${result.content[0].text}`;
+                    if (gate.warning)
+                        result.content[0].text = `⚠️ ${gate.warning}\n\n${result.content[0].text}`;
                 }
+                if (gate.build)
+                    result._meta = { ...(result._meta ?? {}), 'pinepaper.studio/build': gate.build };
                 return result;
             }
             case 'pinepaper_agent_end_job': {
@@ -3883,6 +4176,8 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         'pinepaper_query_capabilities',
                         // Deformation, sprite sheets, interaction
                         'pinepaper_deform',
+                        'pinepaper_hand_drawn',
+                        'pinepaper_pen_figure',
                         'pinepaper_sprite_sheet',
                         'pinepaper_interaction',
                         // Widget export