@pixerate/editor 0.167.0 → 0.168.0

package/dist/{chunk-6DM3PUQD.cjs → chunk-CYKWYP6D.cjs}

@@ -192,9 +192,11 @@ async function createEffectAuthoringSession(source, options) {
   let playing = false;
   let cancelSchedule = null;
   let lastScheduleTime = null;
-  let playheadTime = 0;
   let duration = _nullishCoalesce(_nullishCoalesce(_optionalChain([initialDoc, 'optionalAccess', _ => _.duration]), () => ( description.duration)), () => ( 1e3));
   if (!(duration > 0)) duration = 1e3;
+  const start = options.startTime;
+  let playheadTime = typeof start === "number" && Number.isFinite(start) ? Math.max(0, Math.min(duration, start)) : duration / 2;
+  let previewError = null;
   let loop = _nullishCoalesce(_nullishCoalesce(_optionalChain([initialDoc, 'optionalAccess', _2 => _2.loop]), () => ( description.loop)), () => ( false));
   let compiled = null;
   let savedPresets = initialDoc ? [..._nullishCoalesce(initialDoc.presets, () => ( []))] : [];
@@ -258,6 +260,7 @@ async function createEffectAuthoringSession(source, options) {
       tracks: { ...tracks },
       issues: [],
       compiled,
+      previewError,
       time: playheadTime,
       duration,
       loop,
@@ -704,8 +707,23 @@ async function createEffectAuthoringSession(source, options) {
       if (disposed) {
         throw new (0, _chunkRUZQMYXHcjs.EffectDisposedError)(effectId);
       }
-      const renderer = await provider.createRenderer(effectId, opts);
+      let renderer;
+      try {
+        renderer = await provider.createRenderer(effectId, opts);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const reason = description.kind === "vector" ? `No pixel preview for this vector effect: ${message}` : `No pixel preview: ${message}`;
+        if (previewError !== reason) {
+          previewError = reason;
+          invalidateState();
+        }
+        throw e;
+      }
       livePreviews.add(renderer);
+      if (previewError !== null) {
+        previewError = null;
+        invalidateState();
+      }
       const preview = {
         effectId: renderer.effectId,
         width: renderer.width,

package/dist/{chunk-ZGOHKS3X.js → chunk-HCC2LBCW.js}

@@ -192,9 +192,11 @@ async function createEffectAuthoringSession(source, options) {
   let playing = false;
   let cancelSchedule = null;
   let lastScheduleTime = null;
-  let playheadTime = 0;
   let duration = initialDoc?.duration ?? description.duration ?? 1e3;
   if (!(duration > 0)) duration = 1e3;
+  const start = options.startTime;
+  let playheadTime = typeof start === "number" && Number.isFinite(start) ? Math.max(0, Math.min(duration, start)) : duration / 2;
+  let previewError = null;
   let loop = initialDoc?.loop ?? description.loop ?? false;
   let compiled = null;
   let savedPresets = initialDoc ? [...initialDoc.presets ?? []] : [];
@@ -258,6 +260,7 @@ async function createEffectAuthoringSession(source, options) {
       tracks: { ...tracks },
       issues: [],
       compiled,
+      previewError,
       time: playheadTime,
       duration,
       loop,
@@ -704,8 +707,23 @@ async function createEffectAuthoringSession(source, options) {
       if (disposed) {
         throw new EffectDisposedError(effectId);
       }
-      const renderer = await provider.createRenderer(effectId, opts);
+      let renderer;
+      try {
+        renderer = await provider.createRenderer(effectId, opts);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const reason = description.kind === "vector" ? `No pixel preview for this vector effect: ${message}` : `No pixel preview: ${message}`;
+        if (previewError !== reason) {
+          previewError = reason;
+          invalidateState();
+        }
+        throw e;
+      }
       livePreviews.add(renderer);
+      if (previewError !== null) {
+        previewError = null;
+        invalidateState();
+      }
       const preview = {
         effectId: renderer.effectId,
         width: renderer.width,

package/dist/effects/authoring-session.d.cts

@@ -17,6 +17,11 @@ export interface GenericAuthoringOptions {
     schedule?: (frame: (now: number) => void) => () => void;
     /** Ms within which `setValue` calls on one control with no gesture merge (default 400). */
     mergeWindowMs?: number;
+    /**
+     * Where the playhead starts (ms, clamped to 0..duration). Default: half the duration, as
+     * catalog thumbnails do, so entrance-style effects and transitions open on a frame that shows them.
+     */
+    startTime?: number;
 }
 /**
  * Creates an effect authoring session with values, presets, keyframes, timing and undo

package/dist/effects/authoring-session.d.ts

@@ -17,6 +17,11 @@ export interface GenericAuthoringOptions {
     schedule?: (frame: (now: number) => void) => () => void;
     /** Ms within which `setValue` calls on one control with no gesture merge (default 400). */
     mergeWindowMs?: number;
+    /**
+     * Where the playhead starts (ms, clamped to 0..duration). Default: half the duration, as
+     * catalog thumbnails do, so entrance-style effects and transitions open on a frame that shows them.
+     */
+    startTime?: number;
 }
 /**
  * Creates an effect authoring session with values, presets, keyframes, timing and undo

package/dist/effects/authoring.d.cts

@@ -65,6 +65,12 @@ export interface EffectAuthoringState {
     issues: readonly EffectAuthoringIssue[];
     /** Whether the source compiled: true, false, or null when that is not known yet (no preview has compiled it). */
     compiled: boolean | null;
+    /**
+     * Why `createPreview` could not make a pixel preview (for example a vector effect whose provider
+     * only draws it as SVG), or null when it could or has not been asked yet. Optional for sessions
+     * that never fail to preview.
+     */
+    previewError?: string | null;
     /** Current playhead position (ms). */
     time: number;
     /** Length of one play (ms). */

package/dist/effects/authoring.d.ts

@@ -65,6 +65,12 @@ export interface EffectAuthoringState {
     issues: readonly EffectAuthoringIssue[];
     /** Whether the source compiled: true, false, or null when that is not known yet (no preview has compiled it). */
     compiled: boolean | null;
+    /**
+     * Why `createPreview` could not make a pixel preview (for example a vector effect whose provider
+     * only draws it as SVG), or null when it could or has not been asked yet. Optional for sessions
+     * that never fail to preview.
+     */
+    previewError?: string | null;
     /** Current playhead position (ms). */
     time: number;
     /** Length of one play (ms). */

package/dist/effects/index.cjs

@@ -3,7 +3,7 @@
 var _chunkFKUKJ3XAcjs = require('../chunk-FKUKJ3XA.cjs');
 
 
-var _chunk6DM3PUQDcjs = require('../chunk-6DM3PUQD.cjs');
+var _chunkCYKWYP6Dcjs = require('../chunk-CYKWYP6D.cjs');
 
 
 var _chunkPY4GWSE2cjs = require('../chunk-PY4GWSE2.cjs');
@@ -568,7 +568,7 @@ function createFakeEffectProvider(options = {}) {
       };
     },
     ...supportsAuthoring ? {
-      openAuthoring: (from) => _chunk6DM3PUQDcjs.createEffectAuthoringSession.call(void 0, from, { provider })
+      openAuthoring: (from) => _chunkCYKWYP6Dcjs.createEffectAuthoringSession.call(void 0, from, { provider })
     } : {}
   };
   return provider;
@@ -738,7 +738,7 @@ function createEffectAuthoringToolProvider(host, options) {
   const describeTool = {
     name: "effect_authoring_describe",
     title: "Describe open effect",
-    description: "Describes the effect currently open for authoring: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, duration, loop, and compile issues.",
+    description: "Describes the effect currently open for authoring: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, playhead time, duration, loop, compile issues, and previewError: why there is no pixel preview (e.g. a vector effect the provider only draws as SVG), or null.",
     inputSchema: object({}),
     annotations: { title: "Describe open effect", ...ANNOTATIONS.read },
     handler: () => {
@@ -755,9 +755,11 @@ function createEffectAuthoringToolProvider(host, options) {
           control,
           keyframes: track.length
         })),
+        time: state.time,
         duration: state.duration,
         loop: state.loop,
-        issues: state.issues
+        issues: state.issues,
+        previewError: _nullishCoalesce(state.previewError, () => ( null))
       };
     }
   };
@@ -1013,7 +1015,7 @@ function createEffectAuthoringToolProvider(host, options) {
   const viewTool = {
     name: "effect_authoring_view",
     title: "View effect preview image",
-    description: "Captures an image of the effect preview at the current playhead time or at a specified time in milliseconds.",
+    description: "Captures an image of the effect preview at the current playhead time or at a specified time in milliseconds. Refused, with the reason, when the effect has no pixel preview (see previewError in effect_authoring_describe).",
     inputSchema: object({
       time: { type: "number", minimum: 0, description: "Optional time in milliseconds to view the preview at. Moves playhead to this time before capturing." }
     }),
@@ -1021,6 +1023,10 @@ function createEffectAuthoringToolProvider(host, options) {
     handler: async (args) => {
       const session = requireSession();
       if (!host.capture) throw new Error("Capturing a preview image is not supported by this host.");
+      const previewError = session.getState().previewError;
+      if (previewError) {
+        throw new Error(`${previewError} The other effect authoring tools still work; check values with effect_authoring_describe.`);
+      }
       if (args.time !== void 0) {
         if (typeof args.time !== "number" || !Number.isFinite(args.time) || args.time < 0) {
           throw new Error("time must be a finite non-negative number.");
@@ -1107,4 +1113,4 @@ function createEffectAuthoringToolProvider(host, options) {
 
 
 
-exports.EFFECT_ERROR_CODES = _chunkRUZQMYXHcjs.EFFECT_ERROR_CODES; exports.EFFECT_KINDS = _chunkRUZQMYXHcjs.EFFECT_KINDS; exports.EFFECT_USES = _chunkRUZQMYXHcjs.EFFECT_USES; exports.EFFECT_USE_LABELS = EFFECT_USE_LABELS; exports.EffectControlError = _chunkRUZQMYXHcjs.EffectControlError; exports.EffectDisposedError = _chunkRUZQMYXHcjs.EffectDisposedError; exports.EffectError = _chunkRUZQMYXHcjs.EffectError; exports.EffectRendererPool = _chunkPY4GWSE2cjs.EffectRendererPool; exports.EffectUnsupportedError = _chunkRUZQMYXHcjs.EffectUnsupportedError; exports.EffectsSlot = _chunkRUZQMYXHcjs.EffectsSlot; exports.NoEffectsProviderError = _chunkRUZQMYXHcjs.NoEffectsProviderError; exports.UnknownEffectError = _chunkRUZQMYXHcjs.UnknownEffectError; exports.applyEffectMask = _chunkRUZQMYXHcjs.applyEffectMask; exports.checkEffectProvider = checkEffectProvider; exports.createEffectAuthoringSession = _chunk6DM3PUQDcjs.createEffectAuthoringSession; exports.createEffectAuthoringToolProvider = createEffectAuthoringToolProvider; exports.createEffectPixels = _chunkRUZQMYXHcjs.createEffectPixels; exports.createEffectToolProvider = _chunkRUZQMYXHcjs.createEffectToolProvider; exports.createFakeEffectProvider = createFakeEffectProvider; exports.effectControlField = effectControlField; exports.effectFieldValue = effectFieldValue; exports.effectFontFamilies = effectFontFamilies; exports.effectParameterFields = effectParameterFields; exports.effectSampleInputs = effectSampleInputs; exports.effectSamplePicture = effectSamplePicture; exports.effectValueErrors = _chunkRUZQMYXHcjs.effectValueErrors; exports.encodeEffectFloat = _chunkRUZQMYXHcjs.encodeEffectFloat; exports.groupEffectsByCategory = groupEffectsByCategory; exports.isEffectError = _chunkRUZQMYXHcjs.isEffectError; exports.isEffectFontControl = isEffectFontControl; exports.isEffectPixels = _chunkRUZQMYXHcjs.isEffectPixels; exports.linearToSrgb = _chunkRUZQMYXHcjs.linearToSrgb; exports.renderEffectThumbnail = renderEffectThumbnail; exports.resolveEffectValues = _chunkRUZQMYXHcjs.resolveEffectValues; exports.searchEffectSummaries = _chunkRUZQMYXHcjs.searchEffectSummaries; exports.srgbToLinear = _chunkRUZQMYXHcjs.srgbToLinear;
+exports.EFFECT_ERROR_CODES = _chunkRUZQMYXHcjs.EFFECT_ERROR_CODES; exports.EFFECT_KINDS = _chunkRUZQMYXHcjs.EFFECT_KINDS; exports.EFFECT_USES = _chunkRUZQMYXHcjs.EFFECT_USES; exports.EFFECT_USE_LABELS = EFFECT_USE_LABELS; exports.EffectControlError = _chunkRUZQMYXHcjs.EffectControlError; exports.EffectDisposedError = _chunkRUZQMYXHcjs.EffectDisposedError; exports.EffectError = _chunkRUZQMYXHcjs.EffectError; exports.EffectRendererPool = _chunkPY4GWSE2cjs.EffectRendererPool; exports.EffectUnsupportedError = _chunkRUZQMYXHcjs.EffectUnsupportedError; exports.EffectsSlot = _chunkRUZQMYXHcjs.EffectsSlot; exports.NoEffectsProviderError = _chunkRUZQMYXHcjs.NoEffectsProviderError; exports.UnknownEffectError = _chunkRUZQMYXHcjs.UnknownEffectError; exports.applyEffectMask = _chunkRUZQMYXHcjs.applyEffectMask; exports.checkEffectProvider = checkEffectProvider; exports.createEffectAuthoringSession = _chunkCYKWYP6Dcjs.createEffectAuthoringSession; exports.createEffectAuthoringToolProvider = createEffectAuthoringToolProvider; exports.createEffectPixels = _chunkRUZQMYXHcjs.createEffectPixels; exports.createEffectToolProvider = _chunkRUZQMYXHcjs.createEffectToolProvider; exports.createFakeEffectProvider = createFakeEffectProvider; exports.effectControlField = effectControlField; exports.effectFieldValue = effectFieldValue; exports.effectFontFamilies = effectFontFamilies; exports.effectParameterFields = effectParameterFields; exports.effectSampleInputs = effectSampleInputs; exports.effectSamplePicture = effectSamplePicture; exports.effectValueErrors = _chunkRUZQMYXHcjs.effectValueErrors; exports.encodeEffectFloat = _chunkRUZQMYXHcjs.encodeEffectFloat; exports.groupEffectsByCategory = groupEffectsByCategory; exports.isEffectError = _chunkRUZQMYXHcjs.isEffectError; exports.isEffectFontControl = isEffectFontControl; exports.isEffectPixels = _chunkRUZQMYXHcjs.isEffectPixels; exports.linearToSrgb = _chunkRUZQMYXHcjs.linearToSrgb; exports.renderEffectThumbnail = renderEffectThumbnail; exports.resolveEffectValues = _chunkRUZQMYXHcjs.resolveEffectValues; exports.searchEffectSummaries = _chunkRUZQMYXHcjs.searchEffectSummaries; exports.srgbToLinear = _chunkRUZQMYXHcjs.srgbToLinear;

package/dist/effects/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-CJE5MOIS.js";
 import {
   createEffectAuthoringSession
-} from "../chunk-ZGOHKS3X.js";
+} from "../chunk-HCC2LBCW.js";
 import {
   EffectRendererPool
 } from "../chunk-EHLOCVWB.js";
@@ -738,7 +738,7 @@ function createEffectAuthoringToolProvider(host, options) {
   const describeTool = {
     name: "effect_authoring_describe",
     title: "Describe open effect",
-    description: "Describes the effect currently open for authoring: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, duration, loop, and compile issues.",
+    description: "Describes the effect currently open for authoring: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, playhead time, duration, loop, compile issues, and previewError: why there is no pixel preview (e.g. a vector effect the provider only draws as SVG), or null.",
     inputSchema: object({}),
     annotations: { title: "Describe open effect", ...ANNOTATIONS.read },
     handler: () => {
@@ -755,9 +755,11 @@ function createEffectAuthoringToolProvider(host, options) {
           control,
           keyframes: track.length
         })),
+        time: state.time,
         duration: state.duration,
         loop: state.loop,
-        issues: state.issues
+        issues: state.issues,
+        previewError: state.previewError ?? null
       };
     }
   };
@@ -1013,7 +1015,7 @@ function createEffectAuthoringToolProvider(host, options) {
   const viewTool = {
     name: "effect_authoring_view",
     title: "View effect preview image",
-    description: "Captures an image of the effect preview at the current playhead time or at a specified time in milliseconds.",
+    description: "Captures an image of the effect preview at the current playhead time or at a specified time in milliseconds. Refused, with the reason, when the effect has no pixel preview (see previewError in effect_authoring_describe).",
     inputSchema: object({
       time: { type: "number", minimum: 0, description: "Optional time in milliseconds to view the preview at. Moves playhead to this time before capturing." }
     }),
@@ -1021,6 +1023,10 @@ function createEffectAuthoringToolProvider(host, options) {
     handler: async (args) => {
       const session = requireSession();
       if (!host.capture) throw new Error("Capturing a preview image is not supported by this host.");
+      const previewError = session.getState().previewError;
+      if (previewError) {
+        throw new Error(`${previewError} The other effect authoring tools still work; check values with effect_authoring_describe.`);
+      }
       if (args.time !== void 0) {
         if (typeof args.time !== "number" || !Number.isFinite(args.time) || args.time < 0) {
           throw new Error("time must be a finite non-negative number.");

package/dist/video-editor/index.cjs

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6; var _class7;
 
-var _chunk6DM3PUQDcjs = require('../chunk-6DM3PUQD.cjs');
+var _chunkCYKWYP6Dcjs = require('../chunk-CYKWYP6D.cjs');
 
 
 
@@ -6136,7 +6136,7 @@ async function openVideoClipEffectAuthoring(controller, clip, instance, options
   const at = _chunk3OSXHLITcjs.findVideoClip.call(void 0, controller.getProject(), clip);
   if (!at) throw new Error(`There is no clip "${clip}".`);
   const doc = videoClipEffectDocument(at.clip, instance, provider.id);
-  const session = await _chunk6DM3PUQDcjs.createEffectAuthoringSession.call(void 0, { document: doc }, { ...options, provider });
+  const session = await _chunkCYKWYP6Dcjs.createEffectAuthoringSession.call(void 0, { document: doc }, { ...options, provider });
   return {
     clip,
     instance,

package/dist/video-editor/index.js

@@ -1,6 +1,6 @@
 import {
   createEffectAuthoringSession
-} from "../chunk-ZGOHKS3X.js";
+} from "../chunk-HCC2LBCW.js";
 import {
   VIDEO_ADJUSTMENT_SCOPES,
   VIDEO_BLEND_MODES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.167.0",
+  "version": "0.168.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-effect-authoring/SKILL.md

@@ -21,7 +21,9 @@ For general error reporting and undo conventions, see `pixerate-agent-tools`.
 
 1. **Inspect first.** Run `effect_authoring_describe` to inspect the effect name, kind, source
    language (`glsl`, `svg`, or null when the effect has no source to edit), control parameter schemas, current
-   values, existing tracks, and compile issues.
+   values, existing tracks, playhead `time`, compile issues and `previewError`.
+   A session opens with its playhead at half the effect's length (where entrance-style effects and
+   transitions show), so values set on an animated control key that time unless you seek first.
 2. **Read or update source code.** If `sourceLanguage` is non-null, use `effect_authoring_get_source`
    to read the shader or script code. Use `effect_authoring_set_source` to recompile with new code
    and immediately inspect any reported syntax or compilation issues with line numbers.
@@ -38,7 +40,10 @@ For general error reporting and undo conventions, see `pixerate-agent-tools`.
 6. **Save presets.** When an interesting look is achieved, save it with `effect_authoring_save_preset`
    or restore known presets with `effect_authoring_apply_preset`.
 7. **Verify visually.** When `effect_authoring_view` is available, capture rendered preview frames
-   at specific times to visually confirm effect appearance.
+   at specific times to visually confirm effect appearance. When `effect_authoring_describe` reports a
+   `previewError` (typically a `vector` effect whose provider only draws it as SVG), there is no pixel
+   preview: `effect_authoring_view` is refused with that reason, but values, presets, keyframes and
+   timing still work. Judge the result from the values instead of retrying the view.
 
 ## Best practices
 
@@ -56,7 +61,7 @@ For general error reporting and undo conventions, see `pixerate-agent-tools`.
 
 | Tool | Description and usage |
 | --- | --- |
-| `effect_authoring_describe` | Reads the currently open effect session: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, duration, loop, and compile issues. |
+| `effect_authoring_describe` | Reads the currently open effect session: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, playhead `time`, duration, loop, compile issues, and `previewError` (why there is no pixel preview, or null). Call it first. |
 | `effect_authoring_get_source` | Retrieves shader or script source code and language for code-backed effects. Refused if `sourceLanguage` is null. |
 | `effect_authoring_set_source` | Recompiles the effect with new shader or script source code. Returns compiler issues with line numbers and messages. Available only when supported by the session. |
 | `effect_authoring_set_values` | Sets one or more control values at the current playhead time as a single undo step. Rejects all changes if any control name or value is invalid. |
@@ -70,11 +75,13 @@ For general error reporting and undo conventions, see `pixerate-agent-tools`.
 | `effect_authoring_seek` | Moves the preview playhead to a specific timeline position in milliseconds (clamped to 0..duration) and returns values at that time. |
 | `effect_authoring_undo` | Undoes the most recent edit in the authoring session. |
 | `effect_authoring_redo` | Redoes the most recently undone edit in the authoring session. |
-| `effect_authoring_view` | Captures a preview image of the effect at the current playhead or a specified timestamp. Available when preview capture is supported. |
+| `effect_authoring_view` | Captures a preview image of the effect at the current playhead or a specified timestamp. Available when preview capture is supported. Refused, with the reason, when `effect_authoring_describe` shows a `previewError`. |
 
 ## Pitfalls
 
 - Calling authoring tools when no authoring session is open returns an error explaining that a session must be opened first.
 - Animated controls calculate their values dynamically from keyframes; clearing a track reverts the parameter to static behavior.
 - Compiling invalid shader code produces issues in `effect_authoring_set_source`; inspect the line numbers and messages to correct syntax.
+- A `vector` effect may have no pixel preview (the provider refuses a pixel renderer); check `previewError` rather than reading a blank capture as a broken effect.
+- The playhead does not start at 0. Pass explicit `time`s to `effect_authoring_set_keyframe`, or `effect_authoring_seek` before setting values on an animated control.
 - Control values must match their schema types and bounds; colours must be `#rrggbb` (or `#rrggbbaa`), and numbers must fall within `[min, max]`.