@pinepaper.studio/mcp-server 1.6.9 → 1.6.10

package/dist/tools/definitions.js

@@ -3117,6 +3117,14 @@ USE WHEN:
 - Prototyping new features
 - A scene whose repetition is the point: dozens of items built in a loop. This is the cheapest route by an order of magnitude — a 63-item animated scene is ~4k characters here against ~147k as keyframe tool calls — because the loop collapses the repetition instead of restating it per item. Synchronous build work is bounded by the governor's 4s deadline, which such a scene fits easily.
 
+ENGINE SEMANTICS THAT BITE RAW-JS AUTHORS. The tool schemas protect tool callers from these; writing JS opts out of that protection, and each of these fails SILENTLY:
+- app.create() returns a Paper.js item whose .id is a NUMBER. The id every tool and relation wants is the STRING at item.data.registryId ('item_1'). Passing the number to addAnimation throws "Cannot create property 'data' on number".
+- app.create() with an unknown type returns undefined and creates nothing — 'rect' is not 'rectangle'. The schema catches that for tool callers; a loop does not.
+- app.addAnimation(id, keyframeArray, options) takes a real ARRAY. A JSON string installs nothing, silently, and the scene exports frozen. It also returns without error on an id that does not resolve.
+- Keyframes live at item.data.keyframes. app.keyframeItems is not the live store, so probing it reports false negatives.
+- transformOrigin is IGNORED by the keyframe engine: rotation always pivots on the item centre. For true joint pivots use pinepaper_rigging bones, or keyframe computed x/y per joint.
+- Bone angles are RADIANS in the engine and relative to the parent, though pinepaper_rigging converts degrees for you — that conversion is the tool's, not the engine's.
+
 WHAT THE CHEAP ROUTE COSTS, so the choice is deliberate: items built and animated in raw JS carry NO behavioral record. No graph edge, nothing SMIL or widget export can lift, nothing the ontology can read — the scene renders and cannot describe itself. Relations are the canonical behavior surface here, so for motion that is a function of time prefer pinepaper_add_relation with 'time_expression' (still ~5.7x cheaper than keyframes), and for a whole group moving together staggered_with or wave_through. Reach for a loop when the geometry is procedural, not merely to avoid the typing.
 
 AVAILABLE GLOBALS:
@@ -3247,6 +3255,8 @@ BEFORE AUTHORING DENSE TRACKS — three routes are cheaper, and two of them keep
 - PER-ITEM VARIATION across many items → staggered_with or wave_through express the whole group in ONE call. That collapses the 63-fold repetition a per-item time_expression still pays for.
 - GENUINELY PROCEDURAL scenes → pinepaper_execute_custom_code with app.create + app.addAnimation (which attaches keyframe tracks programmatically, so the keyframes are generated rather than typed), at 4k characters for the same scene — cheapest by an order of magnitude, because a loop collapses the repetition entirely. The trade is real and worth making deliberately: raw JS leaves NO behavioral record — no graph edge, nothing SMIL or widget export can lift, nothing the ontology can read. Scene building fits the governor's 4s synchronous deadline easily (it is the injected loop guards, not the 10s async-tail budget, that bites a build loop).
 
+- TEXT THAT CHANGES OVER TIME -> 'content' IS keyframeable, and it is DISCRETE: it holds the current word until the next keyframe and does not tween. One thing worth knowing before you build a cascade out of it. A cascade of N words is N keyframes you have to write out, which is the reason to prefer the call below rather than any limitation. For the common case prefer pinepaper_execute_custom_code with app.textSequence(itemOrId, words, { interval }): ONE item cycling its words in one call, against one item per word with opacity tracks faking the cut. It returns { ok: false, reason } on an id it cannot resolve.
+
 Keyframes are for motion that is AUTHORED, not computed. A track of hundreds of entries produced from a formula is the signal that one of the three above is the right route.
 
 ANIMATABLE PROPERTIES:
@@ -3563,7 +3573,9 @@ Requires maskType and keyframes array.`,
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `[Utility] Get animatable properties for each mask type. Useful for building custom keyframe animations.`,
+        description: `[Utility] MASK properties only, despite the name: which properties each MASK TYPE can animate.
+
+If you are asking what you can animate on a canvas ITEM, this is the wrong tool and its name will not tell you so. The item-side list lives in pinepaper_keyframe_animate's ANIMATABLE PROPERTIES section, and two entries there are DISCRETE rather than interpolated - content and blendMode hold their value until the next keyframe instead of blending toward it. Treating content as tweenable is what makes every word in a cycler appear half a beat early.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -6346,9 +6358,15 @@ ACTIONS:
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Font Studio control — single action-dispatched tool covering the full Studio API. Sixteen previous thin wrappers collapse into this one entry to reduce the tool list footprint without losing capability.
+        description: `Fonts: which ones you can USE, and authoring new ones.
 
-ACTIONS:
+Most of this tool is glyph authoring — drawing a typeface. If you just want to know what font families are available to set on a text item, that is ONE action:
+
+- list_available       — { category?, loadedOnly? }  every family the studio can render, with whether its file is loaded yet
+- check                — { name, text? }             is this family really there, and can it draw THIS string? Pass the text: a font with four glyphs is installed and will still render most characters in the fallback face, and that second answer is the one that decides the pixels. Do NOT rely on document.fonts.check() — it returns true for a family that does not exist.
+- fallbacks            — {}                          which text items on the canvas are silently drawing in something other than the family they asked for
+
+ACTIONS (authoring):
 - show_studio          — {}                          open the Font Studio UI
 - set_name             — { name }                    name the in-progress font
 - get_required_chars   — { set?: string }            list chars to draw (default: minimum)
@@ -6371,6 +6389,7 @@ ACTIONS:
                 action: {
                     type: 'string',
                     enum: [
+                        'list_available', 'check', 'fallbacks',
                         'show_studio', 'set_name', 'get_required_chars', 'get_status',
                         'create_glyph', 'create_space', 'remove_glyph', 'set_metrics',
                         'export', 'load_into_document', 'export_data', 'import_data',
@@ -6378,6 +6397,9 @@ ACTIONS:
                     ],
                     description: 'Font Studio action',
                 },
+                text: { type: 'string', description: 'check: the string you intend to draw. Without it you learn only whether the family is installed, not whether it has glyphs for your characters.' },
+                category: { type: 'string', description: 'list_available: narrow to one category (e.g. display, serif, mono).' },
+                loadedOnly: { type: 'boolean', description: 'list_available: only families whose font file has already loaded. Unloaded ones still render once the studio fetches them.' },
                 name: { type: 'string', description: 'Font name (set_name)' },
                 set: { type: 'string', description: 'Character set name (get_required_chars; default "minimum")' },
                 character: { type: 'string', description: 'Single-character glyph identifier (create_glyph, remove_glyph)' },
@@ -7664,6 +7686,12 @@ Held exports last until released, or until a LATER export needs the space — an
         },
         description: `Smart export with automatic format detection and platform optimization.
 
+WHAT quality ACTUALLY SETS, because it bundles three things and only one of them is "quality": draft = 15fps / 72dpi / compression 0.6, standard = 30fps / 150dpi / 0.85, high = 60fps / 300dpi / 0.95. So asking for high DOUBLES the frame count and the render time against standard. Override either half directly - fps for frame rate, scale for resolution - and leave quality to mean compression.
+
+DOES THIS SURVIVE EXPORT? It is a PATH fact, not a per-feature one, so the rule is short and does not go stale as capabilities land: IF IT TICKS INSIDE THE ENGINE'S UPDATE LOOP, IT EXPORTS. Loop animations, relations, keyframes, generators and camera moves all do - measured frame-by-frame, not assumed. What does NOT survive is anything driven by the wall clock outside that loop, or anything on the realtime recorder path.
+
+If exported frames look frozen, check the SAMPLING before believing it: a loop animation at animationSpeed 1 has a one-second period, so two frames a whole second apart are identical by design. Compare frames that are not a whole number of periods apart.
+
 PLATFORMS & OPTIMAL FORMATS:
 | Platform        | Dimensions | Static | Animated |
 |-----------------|------------|--------|----------|