dsh-read-animation 0.1.0 → 0.1.2

package/lib/admission.js

@@ -6,16 +6,15 @@
  * A pasted animation survives the browser intact: the chat input hands the
  * clipboard's own `File` to the upload path, and that path encodes `image/gif`
  * and `image/webp` unchanged — no canvas, no re-encode. The bytes arrive at the
- * Host whole. The Host then destroys them: `admitPromptContent` runs every image
- * through the attachment normalizer, which is single-frame by construction, and
- * the source is not kept. By the time any tool can see the attachment it is one
- * frame, so `read_animation` cannot help.
+ * Host whole. The attachment normalizer keeps only one frame and discards the
+ * source. DSH 0.2.2 runs it during raw upload, before prompt admission receives
+ * an already-stored image reference.
  *
- * `admitPromptContent` is the last moment the original bytes exist. This module
- * wraps it to decode the animation and store the frames — and then returns the
- * original result **unchanged**, so the message a person wrote stays exactly what
- * they wrote. `./display.js` serves the animation itself back to the UI, and
- * `./model.js` turns the frames into the model's own copy of that image.
+ * Both raw uploads and legacy encoded prompt admission call `saveImages`. This
+ * module captures its raw inputs against the returned references, before the
+ * caller can discard those bytes. The returned references remain unchanged.
+ * `./display.js` serves the animation itself back to the UI, and `./model.js`
+ * turns the frames into the model's own copy of that image.
  *
  * ### Why it is written defensively
  *
@@ -39,8 +38,8 @@ const ANIMATED_MEDIA_TYPES = new Set(['image/gif', 'image/webp'])
 const SUPPORTED_FORMATS = new Set(['gif', 'webp'])
 
 /**
- * Wrap the attachment service's prompt admission so a pasted animation's frames
- * are captured before the source bytes are discarded.
+ * Wrap image storage so uploaded and pasted animations are captured while their
+ * source bytes are still available.
  *
  * @param ctx - the plugin context; needs the mounted `attachments` service.
  * @param settings - the resolved plugin configuration.
@@ -53,27 +52,27 @@ export function installAdmissionCapture(ctx, settings, pasted) {
     warn(ctx, 'no attachment service is mounted; a pasted animation stays a single frame')
     return false
   }
-  if (typeof attachments.admitPromptContent !== 'function') {
-    warn(ctx, 'attachments.admitPromptContent is not a function; a pasted animation stays a single frame')
+  if (typeof attachments.saveImages !== 'function') {
+    warn(ctx, 'attachments.saveImages is not a function; a pasted animation stays a single frame')
     return false
   }
 
-  const patch = wrapServiceMethod(attachments, 'admitPromptContent', (base) =>
-    async function admitPromptContentCapturingAnimations(content) {
-      // The caller's result is never modified. Capture is best-effort and runs on
-      // the side; if it fails, the message is still exactly what was sent.
-      const admitted = await base(content)
+  const patch = wrapServiceMethod(attachments, 'saveImages', (base) =>
+    async function saveImagesCapturingAnimations(inputs) {
+      // Capture only after the host accepts the batch. Keep its references even
+      // if animation capture fails.
+      const refs = await base(inputs)
       try {
-        await capture(ctx, settings, pasted, content, admitted)
+        await capture(ctx, settings, pasted, inputs, refs)
       } catch (error) {
         warn(ctx, `could not capture a pasted animation: ${describe(error)}`)
       }
-      return admitted
+      return refs
     },
   )
 
   if (!patch.installed) {
-    warn(ctx, 'the admission wrapper did not take effect; a pasted animation stays a single frame')
+    warn(ctx, 'the image-storage wrapper did not take effect; a pasted animation stays a single frame')
     return false
   }
 
@@ -82,37 +81,36 @@ export function installAdmissionCapture(ctx, settings, pasted) {
 }
 
 /**
- * Decode each claimed image and record its frames against the admitted reference.
+ * Decode each claimed image and record its frames against the stored reference.
  *
  * @param ctx - the plugin context.
  * @param settings - the resolved plugin configuration.
  * @param pasted - the store to record into.
- * @param content - the parts as submitted, carrying the original bytes.
- * @param admitted - the parts the service returned, carrying the references.
+ * @param inputs - image storage inputs carrying the original bytes.
+ * @param refs - stored references returned in input order.
  */
-async function capture(ctx, settings, pasted, content, admitted) {
-  if (!Array.isArray(content) || !Array.isArray(admitted)) return
+async function capture(ctx, settings, pasted, inputs, refs) {
+  if (!Array.isArray(inputs) || !Array.isArray(refs)) return
 
   const claimed = []
-  content.forEach((part, index) => {
-    if (part?.type === 'image' && ANIMATED_MEDIA_TYPES.has(part.mediaType)) claimed.push(index)
+  inputs.forEach((input, index) => {
+    if (ANIMATED_MEDIA_TYPES.has(input?.mediaType)) claimed.push(index)
   })
   if (claimed.length === 0) return
 
   const limits = ctx.get('attachments')?.imageLimits
-  const stillImages = content.filter((part) => part?.type === 'image').length - claimed.length
+  const stillImages = inputs.length - claimed.length
   const allowance = Math.max(0, (limits?.maxImagesPerMessage ?? 20) - stillImages)
   const perAnimation = Math.min(settings.maxFrames, Math.floor(allowance / claimed.length))
   if (perAnimation < 2) return
 
   const sharp = loadSharp()
   for (const index of claimed) {
-    const target = admitted[index]
-    const attachmentId = target?.type === 'image' ? target.attachment?.attachmentId : undefined
+    const attachmentId = refs[index]?.attachmentId
     if (attachmentId === undefined) continue
 
-    const part = content[index]
-    const bytes = Buffer.from(part.data, 'base64')
+    const part = inputs[index]
+    const bytes = Buffer.from(part.data)
     const animation = await probeAnimation(sharp, bytes, { maxPixels: limits?.maxImagePixels })
     if (!SUPPORTED_FORMATS.has(animation.format) || animation.frameCount < 2) continue
 
@@ -124,7 +122,7 @@ async function capture(ctx, settings, pasted, content, admitted) {
       plan.plan,
       { maxEdge: settings.maxEdge, background: settings.background, maxPixels: limits?.maxImagePixels },
     )
-    const refs = await ctx.attachments.saveImages(
+    const frameRefs = await ctx.attachments.saveImages(
       rendered.map((frame) => ({
         data: frame.data,
         mediaType: 'image/png',
@@ -144,7 +142,7 @@ async function capture(ctx, settings, pasted, content, admitted) {
     })
 
     pasted.remember(attachmentId, {
-      frames: refs.map((ref) => ({
+      frames: frameRefs.map((ref) => ({
         attachmentId: ref.attachmentId,
         mediaType: ref.mediaType,
         bytes: ref.bytes,

package/lib/bytes.js

@@ -0,0 +1,31 @@
+/**
+ * Collect a bounded byte stream into one array.
+ *
+ * `readFileStream` hands back an async iterable, and two callers here need the
+ * whole thing in one piece: the display path, which serves an original animation
+ * over the wire, and the tool, which decodes what the store kept verbatim.
+ *
+ * @module dsh-read-animation/bytes
+ */
+
+/**
+ * Drain an async iterable of chunks.
+ *
+ * @param stream - the chunks, in order.
+ * @returns one `Uint8Array` holding all of them.
+ */
+export async function collectBytes(stream) {
+  const chunks = []
+  let total = 0
+  for await (const chunk of stream) {
+    chunks.push(chunk)
+    total += chunk.byteLength
+  }
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const chunk of chunks) {
+    out.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return out
+}

package/lib/display.js

@@ -31,6 +31,7 @@
  * @module dsh-read-animation/display
  */
 
+import { collectBytes } from './bytes.js'
 import { describe, warn, wrapServiceMethod } from './patch.js'
 
 /**
@@ -64,7 +65,7 @@ export function installOriginalDisplay(ctx, pasted) {
       const entry = pasted.lookup(ref?.attachmentId)
       if (entry?.original === undefined) return base(ref, signal)
       try {
-        const data = await collect(attachments.readFileStream(entry.original.file, signal))
+        const data = await collectBytes(attachments.readFileStream(entry.original.file, signal))
         return { ref: displayedRef(ref, entry.original, data.byteLength), data }
       } catch (error) {
         // A missing or unreadable original must not cost the user their picture.
@@ -122,19 +123,3 @@ function displayedRef(ref, original, bytes) {
   }
 }
 
-/** Drain a bounded byte stream into one array. */
-async function collect(stream) {
-  const chunks = []
-  let total = 0
-  for await (const chunk of stream) {
-    chunks.push(chunk)
-    total += chunk.byteLength
-  }
-  const out = new Uint8Array(total)
-  let at = 0
-  for (const chunk of chunks) {
-    out.set(chunk, at)
-    at += chunk.byteLength
-  }
-  return out
-}

package/lib/index.js

@@ -39,6 +39,7 @@ import { createPastedStore } from './pasted.js'
 import { installOriginalDisplay } from './display.js'
 import { installModelFrames } from './model.js'
 import { readAnimation } from './read.js'
+import { missingMethods, warn } from './patch.js'
 import { OUTPUT_SCHEMA, PARAMETERS, TOOL_NAME, describeTool, validateArguments } from './tool.js'
 
 /** Cordis plugin name; matches the `id` of this bundle's `cordis.patch.yml` row. */
@@ -62,15 +63,31 @@ const DEFAULT_MAX_INPUT_BYTES = 64 * 1024 * 1024
 export function apply(ctx, config = {}) {
   const settings = resolveConfig(config)
   ctx.inject(['attachments'], (imageCtx) => {
+    // Say what is missing once, in full, before any installer runs. Partial
+    // mounting is deliberate — the tool still works on a host with `saveImages`
+    // but no `readImageRequest` — so this is a report, not a refusal.
+    const gaps = hostGaps(imageCtx.get('attachments'))
+    if (gaps.length > 0) {
+      warn(
+        ctx,
+        `this DSH build is missing ${gaps.length} thing${gaps.length === 1 ? '' : 's'} read_animation needs: ` +
+          `${gaps.join(', ')}. Supported from DSH ${SUPPORTED_FROM}; parts of this plugin will be inert.`,
+      )
+    }
+
+    let pasted
     if (settings.expandPastedAnimations) {
-      // Capture at admission (the last moment the animation's bytes exist) and
-      // hand the frames to the model at request time. The message is not touched.
-      const pasted = createPastedStore(imageCtx)
+      // Capture raw image storage inputs, then hand the frames to the model at
+      // request time. This covers uploads normalized before prompt admission.
+      pasted = createPastedStore(imageCtx)
       installAdmissionCapture(imageCtx, settings, pasted)
       const display = installOriginalDisplay(imageCtx, pasted)
       installModelFrames(imageCtx, pasted, display)
     }
-    registerTool(imageCtx, settings)
+    // The store is handed to the tool as well: a model shown a normalized copy of
+    // a pasted animation reaches for that path first, and the tool can answer with
+    // the animation instead of reporting that the picture has one frame.
+    registerTool(imageCtx, settings, pasted)
   })
 }
 
@@ -101,8 +118,49 @@ function resolveConfig(config) {
   return settings
 }
 
+/**
+ * Attachment-service members this plugin calls, and the DSH version each arrived in.
+ *
+ * The floor is measured, not guessed: reading the published type declarations of
+ * every release shows `0.1.3-alpha.2` as the first version carrying all of these,
+ * and 0.1.2-rc.1 and earlier are missing `saveFile`,
+ * `readImageRequest`, `readFileStream` and `fileHostPath` in various combinations.
+ * `fileHostPath` is deliberately absent from this list: the plugin works without
+ * it, and says less on the sheet when it is missing.
+ */
+const REQUIRED = [
+  { name: 'saveFile', since: '0.1.3-alpha.2' },
+  { name: 'saveImages', since: '0.1.0-rc.7' },
+  { name: 'readImage', since: '0.0.1-rc.1' },
+  { name: 'readImageRequest', since: '0.1.2-alpha.3' },
+  { name: 'readFileStream', since: '0.1.2-alpha.3' },
+]
+
+/** The supported floor, quoted in the message an unsupported host gets. */
+const SUPPORTED_FROM = '0.1.3-alpha.2'
+
+/**
+ * What this host does not provide, in words the person reading the log can act on.
+ *
+ * Checked once at mount. Each installer also guards the method it wraps, but a
+ * guard only covers the method being replaced: a host with `readImage` and no
+ * `saveImages` would mount cleanly and then throw a `TypeError` from inside the
+ * tool, several layers below anything that names the cause.
+ */
+function hostGaps(attachments) {
+  if (attachments === undefined) return ['no attachment service is mounted']
+  const gaps = missingMethods(attachments, REQUIRED.map((entry) => entry.name)).map(
+    (name) => `attachments.${name}() (added in DSH ${REQUIRED.find((entry) => entry.name === name).since})`,
+  )
+  if (attachments.imageLimits === undefined) gaps.push('attachments.imageLimits')
+  else if (typeof attachments.imageLimits.maxImagePixels !== 'number') {
+    gaps.push('attachments.imageLimits.maxImagePixels')
+  }
+  return gaps
+}
+
 /** Build and register the `read_animation` tool definition. */
-function registerTool(ctx, settings) {
+function registerTool(ctx, settings, pasted) {
   ctx.tools.register({
     name: TOOL_NAME,
     description: describeTool(settings),
@@ -116,7 +174,7 @@ function registerTool(ctx, settings) {
     async execute(args, exec) {
       const violations = validateArguments(args)
       if (violations.length > 0) throw new Error(`invalid arguments: ${violations.join('; ')}`)
-      return readAnimation(ctx, settings, args, exec)
+      return readAnimation(ctx, settings, args, exec, pasted)
     },
     presentCall(args) {
       return {

package/lib/model.js

@@ -163,7 +163,7 @@ async function sheetFor(ctx, entry, ref, target, signal, display) {
 
   const sheet = await buildFilmstrip(sharp, {
     tiles,
-    header: headerFor(entry.note?.animation, tiles.length),
+    header: sheetHeader(entry.note?.animation, tiles.length, hostPathOf(ctx, entry)),
     // One tile may be as large as a single frame would have been for this caller:
     // the sheet costs N tiles, not one picture multiplied by N.
     tileMaxWidth: target?.width,
@@ -191,24 +191,52 @@ async function sheetFor(ctx, entry, ref, target, signal, display) {
   }
 }
 
+/**
+ * Where the animation itself is kept, when the store can say.
+ *
+ * The sheet names it so the model has a route to a denser read: eight samples is
+ * what fits in one image, and `read_animation(path, frames: […])` is how it asks
+ * for a specific moment afterwards. Without the path it has to go looking through
+ * the attachment store for the file behind the picture it was sent.
+ */
+function hostPathOf(ctx, entry) {
+  const attachments = ctx.get('attachments')
+  if (attachments === undefined || typeof attachments.fileHostPath !== 'function') return undefined
+  const path = attachments.fileHostPath(entry.original.file)
+  return typeof path === 'string' && path.length > 0 ? path : undefined
+}
+
 /**
  * The sheet's own header: what this animation is, and how it was sampled.
  *
- * Kept short and split in two on purpose. A single long line is not wrapped by
- * anything downstream — the sheet's own layout wraps each line to the canvas, and
- * that works better from meaningful breaks than from one 200-character sentence.
+ * Kept short and split on purpose. A single long line is not wrapped by anything
+ * downstream — the sheet's own layout wraps each line to the canvas, and that
+ * works better from meaningful breaks than from one 200-character sentence.
+ *
+ * Exported so the preview script renders the same text the model is handed,
+ * instead of a second copy that can drift from this one.
+ *
+ * @param animation - the captured animation's facts, when available.
+ * @param sampled - how many tiles the sheet holds.
+ * @param originalPath - where the animation itself is kept, when known.
+ * @returns the header, lines separated by newlines.
  */
-function headerFor(animation, sampled) {
+export function sheetHeader(animation, sampled, originalPath) {
   if (animation === undefined) return `${sampled} sampled frames of one animation, in reading order`
   const total = animation.frameCount
   const fps =
     total > 1 && animation.durationMs > 0 ? ` · ~${Math.round((total * 1000) / animation.durationMs)} fps` : ''
   const timing = animation.minDelayMs === animation.maxDelayMs ? '' : ' · uneven timing'
   const loops = animation.loopsForever === true ? ' · loops forever' : ''
+  const source =
+    originalPath === undefined
+      ? `All ${total} frames are in the file this was pasted from`
+      : `All ${total} frames are at ${originalPath}`
   return (
     `${animation.mediaType} · ${animation.width}x${animation.height} px · ${total} frames · ` +
     `${animation.durationMs} ms${fps}${timing}${loops}\n` +
     `The ${sampled} tiles below are evenly spaced samples in reading order; ` +
-    `each frame's index, duration and start time is printed under it.`
+    `each frame's index, duration and start time is printed under it.\n` +
+    `${source} — read_animation on that path with explicit frame indices looks closer at any moment.`
   )
 }

package/lib/pacing.js

@@ -0,0 +1,217 @@
+/**
+ * Where an animation's change actually is, and which frames to show because of it.
+ *
+ * ### Why this exists
+ *
+ * Sampling a fixed number of frames at equal intervals answers "what does this
+ * animation look like", which is not the same question as "how does it go". The
+ * budget is spread over *time*, while an animation's content lives in *change*: a
+ * long hold at either end gets the same share as the moment something happens.
+ *
+ * Measured on a real 56-frame clip: even sampling spent three of its eight tiles
+ * on the opening where the frame-to-frame change is 1-6 (of 255), and never
+ * sampled the single largest change in the clip (frame 53, change 31.4). Padded to
+ * 136 frames with held ends — what a trimmed screen recording looks like — five of
+ * the eight tiles were pixel-identical to their neighbour.
+ *
+ * ### What it deliberately does not do
+ *
+ * It does not replace coverage with content. The literature on keyframe selection
+ * is split: content-aware selection wins on information-dense questions and
+ * uniform sampling keeps an edge on temporal continuity, which is exactly what a
+ * story is made of. So the equal-interval skeleton is kept, and a tile is moved
+ * **only when the stretch around it is measured to be still** — meaning that tile
+ * and its neighbour show the same picture and nothing is lost by moving it. When
+ * nothing qualifies, this returns the even picks unchanged.
+ *
+ * The module is pure: the caller decodes the frames (including the in-between
+ * probes) and this decides. That keeps the decision testable without an image
+ * library, and keeps the cost of probing a caller concern.
+ *
+ * @module dsh-read-animation/pacing
+ */
+
+/**
+ * Mean absolute pixel difference between two frames, on the 0-255 scale.
+ *
+ * Measured on real material: held frames score 0.0, a slow intro scores 1-6, and
+ * action scores 12-31. The two thresholds below come from that spread rather than
+ * from taste.
+ */
+export function changeBetween(a, b) {
+  const length = Math.min(a.length, b.length)
+  if (length === 0) return 0
+  let total = 0
+  for (let at = 0; at < length; at += 1) total += Math.abs(a[at] - b[at])
+  return total / length
+}
+
+/** Below this, two frames are the same picture for any practical purpose. */
+export const STILL = 2
+
+/** Above this, something is happening between the two frames. */
+export const BUSY = 8
+
+/**
+ * Describe the change in every gap between consecutive chosen frames.
+ *
+ * A gap is probed once, in the middle, and the two halves are compared: a gap
+ * whose middle differs from both ends is a gap where something moved.
+ *
+ * @param chosen - the frame indices that will be shown, in order.
+ * @param decoded - `Map<index, Uint8Array>` of greyscale pixels, holding at least
+ *   the chosen frames and whatever {@link probePlan} asked for in between.
+ * @param frameCount - frames in the whole animation.
+ * @returns per-gap facts, plus which gaps are still and which are busy.
+ */
+export function analyzePacing(chosen, decoded, frameCount) {
+  const at = (index) => decoded.get(index)
+
+  const gaps = []
+  for (let slot = 1; slot < chosen.length; slot += 1) {
+    const from = chosen[slot - 1]
+    const to = chosen[slot]
+    const middle = Math.round((from + to) / 2)
+    const left = at(from)
+    const right = at(to)
+    if (left === undefined || right === undefined) continue
+
+    const between = middle > from && middle < to ? at(middle) : undefined
+    const change =
+      between === undefined
+        ? changeBetween(left, right)
+        : Math.max(changeBetween(left, between), changeBetween(between, right))
+
+    gaps.push({ from, to, frames: to - from, change, still: change < STILL, busy: change > BUSY })
+  }
+
+  const busiest = gaps.reduce((best, gap) => (best === undefined || gap.change > best.change ? gap : best), undefined)
+
+  // How much of each end is still, which is what tells a reader where the story
+  // is rather than where the file happens to start.
+  const firstMoving = gaps.findIndex((gap) => !gap.still)
+  const lastMoving = gaps.length - 1 - [...gaps].reverse().findIndex((gap) => !gap.still)
+
+  return {
+    gaps,
+    busiest,
+    stillGaps: gaps.filter((gap) => gap.still),
+    busyGaps: gaps.filter((gap) => gap.busy),
+    stillUntil: firstMoving > 0 ? gaps[firstMoving].from : undefined,
+    stillFrom: lastMoving >= 0 && lastMoving < gaps.length - 1 ? gaps[lastMoving].to : undefined,
+    frameCount,
+  }
+}
+
+/**
+ * The frames to show, under the chosen strategy.
+ *
+ * `content` removes a tile only when **both** gaps beside it were measured still:
+ * removing it then merges two still stretches into one that is still by the same
+ * measurement, so nothing unmeasured is ever created. The freed tiles go into the
+ * busiest gaps, at the probe that measured them.
+ *
+ * The stricter rule is not caution for its own sake. The first version removed a
+ * tile when *either* neighbour was still, and on a padded clip that produced a
+ * 49-frame gap that had never been probed — a coverage hole presented as a
+ * saving. The constraint that matters is not "no long gaps" but "no *unmeasured*
+ * gaps": a sixty-frame stretch that was measured still is a correctly compressed
+ * hold, and losing it costs nothing.
+ *
+ * @param frameCount - frames in the animation.
+ * @param count - how many frames to choose.
+ * @param pacing - the report from {@link analyzePacing}, or undefined when the
+ *   caller did not probe (in which case only `even` is possible).
+ * @param strategy - `'even'` keeps equal intervals; `'content'` moves only the
+ *   tiles whose surroundings are measured still.
+ * @returns `{ indices, moved }`, where `moved` explains each relocation.
+ */
+export function chooseFrames(frameCount, count, pacing, strategy) {
+  const even = evenIndices(frameCount, count)
+  if (strategy !== 'content' || pacing === undefined || even.length < 3) {
+    return { indices: even, moved: [] }
+  }
+
+  const measured = new Map(pacing.gaps.map((gap) => [`${gap.from}:${gap.to}`, gap]))
+
+  /** The status of the gap between two kept frames, or undefined if nobody measured it. */
+  const gapBetween = (from, to) => {
+    const exact = measured.get(`${from}:${to}`)
+    if (exact !== undefined) return exact
+    const between = pacing.gaps.filter((gap) => gap.from >= from && gap.to <= to)
+    if (between.length === 0 || between.some((gap) => !gap.still)) return undefined
+    return { from, to, frames: to - from, change: Math.max(...between.map((gap) => gap.change)), still: true, busy: false }
+  }
+
+  // Remove the tiles that sit inside a still stretch, at both ends of it. The
+  // first and last frames are never removed: they are the animation's state.
+  const kept = [...even]
+  const freed = []
+  for (let at = even.length - 2; at >= 1; at -= 1) {
+    const before = measured.get(`${even[at - 1]}:${even[at]}`)
+    const after = measured.get(`${even[at]}:${even[at + 1]}`)
+    if (before?.still === true && after?.still === true) {
+      freed.push({ index: even[at], stillChange: Math.max(before.change, after.change) })
+      kept.splice(kept.indexOf(even[at]), 1)
+    }
+  }
+
+  const moved = []
+  for (const freedTile of freed) {
+    // The busiest gap that still has room for a frame in the middle of it.
+    const target = kept
+      .map((from, at) => (at + 1 < kept.length ? gapBetween(from, kept[at + 1]) : undefined))
+      .map((gap, at) => ({ gap, at }))
+      .filter(({ gap }) => gap?.busy === true && gap.frames > 2)
+      .sort((a, b) => b.gap.change - a.gap.change)[0]
+    if (target === undefined) break
+
+    const insert = Math.round((target.gap.from + target.gap.to) / 2)
+    const crowded = kept.some((index) => Math.abs(index - insert) < 2)
+    if (crowded || insert <= 0 || insert >= frameCount - 1) break
+
+    kept.splice(kept.findIndex((index) => index > insert), 0, insert)
+    moved.push({ from: freedTile.index, to: insert, gapChange: target.gap.change, stillChange: freedTile.stillChange })
+  }
+
+  return { indices: kept, moved }
+}
+
+/**
+ * Equal intervals, first and last included.
+ *
+ * This is the sampler the plugin has always used, kept as the default and as the
+ * skeleton the content strategy starts from.
+ */
+export function evenIndices(frameCount, count) {
+  if (frameCount <= 1 || count <= 1) return [0]
+  if (count >= frameCount) return [...Array(frameCount).keys()]
+  const picks = []
+  for (let slot = 0; slot < count; slot += 1) picks.push(Math.round((slot * (frameCount - 1)) / (count - 1)))
+  return [...new Set(picks)]
+}
+
+/**
+ * Where to probe for the change in each gap, without decoding every frame.
+ *
+ * One probe per gap, plus the two ends of the animation so the "still" stretches
+ * can be described. That is `count + 1` extra decodes regardless of how long the
+ * animation is, against `frameCount` for a full change profile — which is what
+ * makes this affordable on a 300-frame clip.
+ *
+ * @param indices - the chosen frames, in order.
+ * @param frameCount - frames in the animation.
+ * @returns `{ samples, probes }` as index lists, deduplicated and in order.
+ */
+export function probePlan(indices, frameCount) {
+  const wanted = new Set(indices)
+  for (let at = 1; at < indices.length; at += 1) {
+    const middle = Math.round((indices[at - 1] + indices[at]) / 2)
+    if (middle > indices[at - 1] && middle < indices[at]) wanted.add(middle)
+  }
+  // The frames just before the first sample and after the last, so an opening or
+  // closing hold is visible rather than inferred.
+  if (indices[0] > 0) wanted.add(indices[0] - 1)
+  if (indices[indices.length - 1] < frameCount - 1) wanted.add(indices[indices.length - 1] + 1)
+  return [...wanted].filter((index) => index >= 0 && index < frameCount).sort((a, b) => a - b)
+}

package/lib/patch.js

@@ -52,6 +52,24 @@ export function isWrapped(value) {
   return typeof value === 'function' && value[LEVEL] !== undefined
 }
 
+/**
+ * Which of `names` the service does not implement.
+ *
+ * Checked before wrapping anything. Installing a wrapper over a method that is not
+ * there used to *create* the property, so the host acquired a function whose only
+ * behaviour was to throw a `TypeError` from deep inside a call that looked
+ * ordinary — and the plugin reported nothing at mount, when it knew the host did
+ * not have what it needed.
+ *
+ * @param service - the service object, or undefined when the service is absent.
+ * @param names - the members this plugin calls.
+ * @returns the missing names, in the order given.
+ */
+export function missingMethods(service, names) {
+  if (service === undefined || service === null) return [...names]
+  return names.filter((name) => typeof service[name] !== 'function')
+}
+
 /**
  * Wrap one method.
  *