dsh-read-animation 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,103 +1,169 @@
-# Changelog
-
-## 0.1.0 — unreleased
-
-Initial version.
-
-### Fixed after an adversarial audit
-
-Four independent reviews (blast radius, plugin code, packaging and lifecycle, then
-an adversarial pass over every high-severity finding) ran before this was
-published. What they found, and what changed:
-
-- **The frame sheet's `variantId` was not a content digest.** It was a hand-rolled
-  `sha256:filmanim…` string, and the DeepSeek adapter validates persisted ids
-  against `/^sha256:[0-9a-f]{64}$/` when it loads its upload index — then swallows
-  the failure into an *empty* index. The effect was not a visible error: it
-  discarded every other session's cached file id and re-uploaded every image.
-  Reproduced against the real exported index class (plugin id: written 1, reloaded
-  0; conforming id: 1/1). It is now the SHA-256 of the bytes being returned, which
-  also stops one on-disk cache entry from aliasing two different byte streams.
-- **The degraded path was worse than the missing feature.** The store reaches the
-  frame it re-encodes through its own `readImage` call, which this plugin wraps, so
-  falling back to the store's request read could hand the model the *whole
-  animation* where it expects one frame. The request path now suspends the
-  animation substitution around that call, and reads its own tiles through the
-  unwrapped read. Pinned by an integration check that breaks a stored frame and
-  asserts the fallback is exactly one frame.
-- **No decoded-pixel ceiling on the `read_animation` path.** `limitInputPixels`
-  was disabled with nothing in its place: a 60 KB file declaring a 9000x9000
-  canvas was refused by the deployment's own attachment store and decoded here
-  anyway, at about 310 MiB. Both the probe and the frame extraction now carry the
-  deployment's `imageLimits.maxImagePixels`.
-- **The sheet cache ignored the size the caller asked for**, so a caller with an
-  8 KiB budget could be served a 28 KB sheet built for a 4 MiB one. The target is
-  now part of the cache key, and a tile is never larger than a single frame would
-  have been for that caller.
-- **The measured header wrap could still be defeated.** A floor of 16 characters
-  kept the loop from reaching a budget that fit, so on a narrow canvas it gave up
-  and returned ink wider than the sheet. The floor is now low enough to be
-  satisfiable, and a canvas too narrow for legible text gets no header at all.
-- **The canvas was composed before it was shrunk**, building a 6156x6306 (about
-  111 MiB) image to throw away. Tile size and grid are settled first.
-- **Torn state files could poison the next record.** A crash part way through an
-  append left a line with no newline, so the following record concatenated onto it
-  and became unreadable too. A torn tail is now detected and compacted away.
-- **The store's bound applied to memory but not to what was read back**, and the
-  log was never compacted. Both fixed; the file is rewritten when it grows past
-  twice the entries worth keeping.
-- **Teardown was last-writer-wins.** Each install captured whatever was on the
-  method, so disposing one left another's patch removed and could reinstall a
-  disposed closure as a permanent own property. Three wrappers now share one
-  installer that resolves its delegate per call, removes cleanly (deleting an
-  inherited property rather than leaving a shadow behind), and reports whether it
-  actually took effect — the previous identity check compared a value that proxy
-  reads always re-wrap, so it could never detect a failed install.
-- **`npm test` did not run the invariant checks.** The no-`@deepseek-ai`-import
-  rule and the bundle/manifest consistency check lived only in the integration
-  harness, which prints SKIP and exits 0 without `DSH_HARNESS_MODULES`. Both now
-  run in `npm test`, which is also the `prepublishOnly` gate.
-- **`files[]` omitted `scripts/`** while `package.json` advertised two npm scripts
-  that live there, so the published package's own scripts were broken.
-
-- **A pasted animation keeps playing in the UI, and the message is left alone.**
-  The browser already uploads an animated GIF/WebP byte-for-byte and labelled as
-  such; the Host flattens it to a single
-  frame during prompt admission and keeps no copy of the source. The plugin wraps
-  `ctx.attachments.admitPromptContent` to capture the frames and the original file
-  at that moment, and `ctx.attachments.readImage` so the UI is served the animation
-  itself (the browser animates whatever bytes that one read returns). What you send
-  is what you send: the chat message is unchanged.
-- **The model now receives a labelled sheet of the frames.** The delivery step is
-  `ctx.attachments.readImageRequest(ref, target, signal)`, the method each adapter
-  calls to build its own copy of one image. It answers with exactly one image, so
-  the frames are composed into a grid chosen to be as square as the sheet budget
-  allows — every tile at its native size, with the frame index, duration and start
-  time printed under each, and the animation's own facts in a wrapped header. The
-  sheet is built once per animation and cached.
-- Rewriting the request from an `llm/stream` listener is **not** used and would not
-  work: a loop-built request arrives deep-frozen ("listeners read it, never rewrite
-  it"), so that earlier attempt silently did nothing.
-- Captured frames and the original are persisted per `$DSH_HOME` in
-  `read-animation/v1/pasted.jsonl`, keyed by the message's attachment id, so a
-  session resumed in a new process still displays — and still delivers — an
-  animation pasted before the restart.
-- A frame's index and start time ride in its attachment display name
-  (`x.gif#frame16@1960ms`), which the harness renders beside the picture once the
-  frames are delivered — so the timing never has to be repeated as message text.
-  (An earlier version of this feature put a header plus one caption per frame into
-  the user's own message; consecutive text parts are concatenated by the UI with
-  no separator, so a one-image message became an unreadable wall.)
-- `read_animation` tool: decodes an animated GIF or animated WebP, samples frames
-  across the timeline (or by explicit index / instant), commits each frame to the
-  attachment store, and returns a header plus one captioned image per frame.
-- Refuses animated PNG by name instead of silently returning its first frame,
-  which is what the host image library does with one.
-- Refuses static images and points at `read_image`; answers a single-frame GIF or
-  WebP with a note that it is not animated.
-- Discloses decode-time substitutions in the model-facing text: zero frame
-  delays treated as 100 ms, missing delays, transparency flattened onto white.
-- The package imports no `@deepseek-ai/*` module at runtime, so it loads both as
-  an installed package and as a `link:`ed checkout. The compiled schemas ship as
-  literals beside their authoring specs, and the integration harness keeps the
-  two in step.
+# Changelog
+
+## 0.1.2 — 2026-11-08
+
+- Fix [#7](https://github.com/NeoHotaru/dsh-read-animation/issues/7). Capture
+  uploaded GIF and animated WebP bytes at `attachments.saveImages`. DSH 0.2.2
+  normalizes uploads before prompt admission, so its stored references previously
+  bypassed capture. Original animation display, model frame sheets, and
+  normalized-copy reads now use the captured source.
+- Add raw-upload regressions through the real attachment store and, on DSH
+  0.2.2, its upload service and receipt resolution. Update the integration fixture
+  for the separate native tool executor and batch execution API.
+
+
+- **The supported DSH range is measured rather than assumed.** The plugin wraps
+  internal service methods, and `engines.dsh` claimed `>=0.1.7-alpha.1` on the
+  strength of one working install. The integration suite now runs against
+  `0.1.3-alpha.2` (the oldest release exposing every member), `0.1.7-alpha.2`,
+  `0.2.0-rc.2` — which is `latest` — and `0.2.1-alpha.3`, all 38/38, and
+  `scripts/check-dsh-compat.py` reads the type declarations of all 32 published
+  releases to find the floor: **0.1.3-alpha.2**. See
+  [COMPATIBILITY.md](COMPATIBILITY.md), including what is *not* claimed.
+- **A host missing a member now says so.** Nothing checked the members the plugin
+  calls before calling them: a host with `readImage` but no `saveImages` mounted
+  cleanly and then threw a `TypeError` from inside the tool. Mount reports every
+  missing member with the release it arrived in, the tool names the reason in its
+  own error, and a test covers the check itself.
+- **`preview-sheet` printed a path that does not exist.** It spelled the store
+  layout as `files/<name>` where the store uses `files/<2>/<digest>/<name>`. The
+  plugin asks `fileHostPath` and was always right; only the script's second copy of
+  the layout could drift.
+- **The integration harness needed `maxPixels` in a request target.** DSH
+  0.1.3-alpha.2 rejects a target without it; later releases default it. A test
+  artefact, not a compatibility problem, but it meant the suite could not run on
+  the floor version at all.
+
+## 0.1.1 — 2026-10-14
+
+Fixed after the first release, from what a live session reported back.
+
+- **`read_animation` follows the path it advertises.** Every image a model receives
+  is shown as a normalized copy at `attachments/v1/objects/<2>/<digest>`, and that
+  is the path a model reaches for when it wants to look at the picture again. For a
+  pasted animation that copy is a single frame, so the tool answered "this picture
+  has one frame": true of that file, and useless as an answer. The tool now resolves
+  that path to the animation this plugin kept, and reports the file the bytes
+  actually came from. A bare `sha256:<digest>` is accepted too.
+- **The sheet says where the animation lives.** Its header ends with the path the
+  store keeps the original at, so a model that wants more than the eight samples can
+  read that path with explicit frame indices instead of searching the attachment
+  store for the file behind the picture it was sent.
+
+## 0.1.0 — 2026-10-14
+
+First release.
+
+Note for anyone publishing a later version, because both releases so far looked like
+failures while they were simply still in flight:
+
+- `npm publish` answers `PUT … 202` and prints "Your package is being processed and
+  may take a few minutes to become available", then exits 0. For a brand-new package
+  name the registry also carries a public `0.0.0-stage` placeholder alongside it.
+  Nothing needs approving in either case.
+- Measured on 0.1.1: the version appeared in the packument **2m41s** after the PUT,
+  and its tarball became downloadable **7m05s** after it. In between, the packument
+  either 404s or lists the version while its tarball still 404s.
+- Check the tarball, not just `npm view versions`, and check it with a GET: a HEAD
+  request to the tarball URL answers 404 even once the tarball is live.
+- A mirror lags further. `registry.npmmirror.com` still served 0.1.0 well after
+  0.1.1 was live on npmjs.org, and a profile configured against it keeps installing
+  the previous version until it syncs.
+
+### Fixed after an adversarial audit
+
+Four independent reviews (blast radius, plugin code, packaging and lifecycle, then
+an adversarial pass over every high-severity finding) ran before this was
+published. What they found, and what changed:
+
+- **The frame sheet's `variantId` was not a content digest.** It was a hand-rolled
+  `sha256:filmanim…` string, and the DeepSeek adapter validates persisted ids
+  against `/^sha256:[0-9a-f]{64}$/` when it loads its upload index — then swallows
+  the failure into an *empty* index. The effect was not a visible error: it
+  discarded every other session's cached file id and re-uploaded every image.
+  Reproduced against the real exported index class (plugin id: written 1, reloaded
+  0; conforming id: 1/1). It is now the SHA-256 of the bytes being returned, which
+  also stops one on-disk cache entry from aliasing two different byte streams.
+- **The degraded path was worse than the missing feature.** The store reaches the
+  frame it re-encodes through its own `readImage` call, which this plugin wraps, so
+  falling back to the store's request read could hand the model the *whole
+  animation* where it expects one frame. The request path now suspends the
+  animation substitution around that call, and reads its own tiles through the
+  unwrapped read. Pinned by an integration check that breaks a stored frame and
+  asserts the fallback is exactly one frame.
+- **No decoded-pixel ceiling on the `read_animation` path.** `limitInputPixels`
+  was disabled with nothing in its place: a 60 KB file declaring a 9000x9000
+  canvas was refused by the deployment's own attachment store and decoded here
+  anyway, at about 310 MiB. Both the probe and the frame extraction now carry the
+  deployment's `imageLimits.maxImagePixels`.
+- **The sheet cache ignored the size the caller asked for**, so a caller with an
+  8 KiB budget could be served a 28 KB sheet built for a 4 MiB one. The target is
+  now part of the cache key, and a tile is never larger than a single frame would
+  have been for that caller.
+- **The measured header wrap could still be defeated.** A floor of 16 characters
+  kept the loop from reaching a budget that fit, so on a narrow canvas it gave up
+  and returned ink wider than the sheet. The floor is now low enough to be
+  satisfiable, and a canvas too narrow for legible text gets no header at all.
+- **The canvas was composed before it was shrunk**, building a 6156x6306 (about
+  111 MiB) image to throw away. Tile size and grid are settled first.
+- **Torn state files could poison the next record.** A crash part way through an
+  append left a line with no newline, so the following record concatenated onto it
+  and became unreadable too. A torn tail is now detected and compacted away.
+- **The store's bound applied to memory but not to what was read back**, and the
+  log was never compacted. Both fixed; the file is rewritten when it grows past
+  twice the entries worth keeping.
+- **Teardown was last-writer-wins.** Each install captured whatever was on the
+  method, so disposing one left another's patch removed and could reinstall a
+  disposed closure as a permanent own property. Three wrappers now share one
+  installer that resolves its delegate per call, removes cleanly (deleting an
+  inherited property rather than leaving a shadow behind), and reports whether it
+  actually took effect — the previous identity check compared a value that proxy
+  reads always re-wrap, so it could never detect a failed install.
+- **`npm test` did not run the invariant checks.** The no-`@deepseek-ai`-import
+  rule and the bundle/manifest consistency check lived only in the integration
+  harness, which prints SKIP and exits 0 without `DSH_HARNESS_MODULES`. Both now
+  run in `npm test`, which is also the `prepublishOnly` gate.
+- **`files[]` omitted `scripts/`** while `package.json` advertised two npm scripts
+  that live there, so the published package's own scripts were broken.
+
+- **A pasted animation keeps playing in the UI, and the message is left alone.**
+  The browser already uploads an animated GIF/WebP byte-for-byte and labelled as
+  such; the Host flattens it to a single
+  frame during prompt admission and keeps no copy of the source. The plugin wraps
+  `ctx.attachments.admitPromptContent` to capture the frames and the original file
+  at that moment, and `ctx.attachments.readImage` so the UI is served the animation
+  itself (the browser animates whatever bytes that one read returns). What you send
+  is what you send: the chat message is unchanged.
+- **The model now receives a labelled sheet of the frames.** The delivery step is
+  `ctx.attachments.readImageRequest(ref, target, signal)`, the method each adapter
+  calls to build its own copy of one image. It answers with exactly one image, so
+  the frames are composed into a grid chosen to be as square as the sheet budget
+  allows — every tile at its native size, with the frame index, duration and start
+  time printed under each, and the animation's own facts in a wrapped header. The
+  sheet is built once per animation and cached.
+- Rewriting the request from an `llm/stream` listener is **not** used and would not
+  work: a loop-built request arrives deep-frozen ("listeners read it, never rewrite
+  it"), so that earlier attempt silently did nothing.
+- Captured frames and the original are persisted per `$DSH_HOME` in
+  `read-animation/v1/pasted.jsonl`, keyed by the message's attachment id, so a
+  session resumed in a new process still displays — and still delivers — an
+  animation pasted before the restart.
+- A frame's index and start time ride in its attachment display name
+  (`x.gif#frame16@1960ms`), which the harness renders beside the picture once the
+  frames are delivered — so the timing never has to be repeated as message text.
+  (An earlier version of this feature put a header plus one caption per frame into
+  the user's own message; consecutive text parts are concatenated by the UI with
+  no separator, so a one-image message became an unreadable wall.)
+- `read_animation` tool: decodes an animated GIF or animated WebP, samples frames
+  across the timeline (or by explicit index / instant), commits each frame to the
+  attachment store, and returns a header plus one captioned image per frame.
+- Refuses animated PNG by name instead of silently returning its first frame,
+  which is what the host image library does with one.
+- Refuses static images and points at `read_image`; answers a single-frame GIF or
+  WebP with a note that it is not animated.
+- Discloses decode-time substitutions in the model-facing text: zero frame
+  delays treated as 100 ms, missing delays, transparency flattened onto white.
+- The package imports no `@deepseek-ai/*` module at runtime, so it loads both as
+  an installed package and as a `link:`ed checkout. The compiled schemas ship as
+  literals beside their authoring specs, and the integration harness keeps the
+  two in step.

package/COMPATIBILITY.md

@@ -0,0 +1,100 @@
+# Compatibility
+
+## Supported range
+
+**DSH 0.1.3-alpha.2 and later.** Upload compatibility rechecked on
+2026-11-08 against DSH 0.2.2-rc.1 and 0.1.7-alpha.2.
+
+## What was measured
+
+### The integration suite, actually run
+
+`test/integration/harness.mjs` boots the real `dsh-fs-local`,
+`dsh-attachment-local`, `dsh-system-prompt` and `dsh-tools` plugins in-process,
+registers the tool, and exercises the paste path through a real `llm.stream`
+dispatch. Pointed at four versions spanning the range:
+
+| DSH | checks |
+| --- | --- |
+| `0.1.3-alpha.2` — the oldest release with the full API | 38/38 |
+| `0.1.7-alpha.2` — the version this was developed against | 38/38 |
+| `0.2.0-rc.2` — `latest` on that date | 38/38 |
+| `0.2.1-alpha.3` — `alpha` on that date, newest | 38/38 |
+
+The table above records the 2026-10-14 baseline. The upload regression checks
+added on 2026-11-08 produced the following results:
+
+| DSH | checks |
+| --- | --- |
+| `0.1.7-alpha.2` — encoded-prompt and raw image-storage paths | 40/40 |
+| `0.2.2-rc.1` — includes the raw upload service and stored-reference admission | 41/41 |
+
+DSH 0.2.2 normalizes uploaded images before prompt admission. Capture now wraps
+`saveImages`, which receives raw bytes for both upload and encoded-prompt paths.
+The regressions check GIF and animated WebP display, frame sheets, and reads of
+normalized-copy paths. The 0.2.2 case also calls the real
+`FileUploads.uploadImageStream` and resolves its receipt into a stored image
+reference. The test harness mounts the native tool executor on hosts that expose
+that separate service.
+
+```sh
+DSH_HARNESS_MODULES=/path/to/dsh/node_modules node test/integration/harness.mjs
+```
+
+### The API surface, read from every published release
+
+`scripts/check-dsh-compat.py` downloads the type declarations of
+`@deepseek-ai/dsh-attachment` and `@deepseek-ai/dsh-attachment-local` for every
+published DSH version and reports which of the members this plugin calls are
+present. DSH publishes its whole monorepo at one version, so `dsh@X` pins
+`dsh-attachment-local@X`.
+
+```sh
+python scripts/check-dsh-compat.py
+```
+
+The result over all 32 published releases: every member is present from
+**0.1.3-alpha.2** onward and absent before it. The members, and the release each
+first appears in:
+
+| member | since |
+| --- | --- |
+| `saveImages` | `0.1.0-rc.7` |
+| `readImageRequest` | `0.1.2-alpha.3` |
+| `readFileStream` | `0.1.2-alpha.3` |
+| `saveFile` | `0.1.3-alpha.2` |
+| `fileHostPath` | `0.1.3-alpha.2` — optional; the plugin works without it |
+
+So the floor is set by `saveFile`, which is what keeps the original animation's
+bytes for the sheet, and by `fileHostPath`. Below `0.1.3-alpha.2` the plugin still
+mounts and still reads animations from files; pasted animations degrade to a
+single frame, and it says which member is missing and when that member arrived.
+
+## What is not claimed
+
+- **Four of the seventeen releases in the range were executed.** Every release in
+  the range was checked to expose the full member list, but a release whose types
+  are complete can still behave differently. The four points span floor to ceiling.
+- **The upper bound is a date, not a guarantee.** This plugin wraps
+  `saveImages`, `readImage`, and `readImageRequest` — internal service
+  methods. A DSH release that changes their signatures or the shape of a request
+  target will break it, and nothing here can detect that in advance.
+- **The `engines.dsh` field is documentation.** npm does not enforce a
+  non-standard `engines` key, and DSH does not read it. It records the measured
+  floor; it does not stop an install.
+
+## Re-measuring after a DSH release
+
+1. `python scripts/check-dsh-compat.py` — does the new release still expose
+   everything?
+2. Install it somewhere and run the suite against it:
+
+   ```sh
+   mkdir /tmp/dsh-probe && cd /tmp/dsh-probe
+   npm init -y && npm i @deepseek-ai/dsh@<version>
+   cd <this repo>
+   DSH_HARNESS_MODULES=/tmp/dsh-probe/node_modules node test/integration/harness.mjs
+   ```
+
+3. If it fails, the check that fails names the method. The messages raised at mount
+   and from the tool also name the missing member and the release it arrived in.

package/README.md

@@ -52,13 +52,13 @@ the chunk stream and refuses it by name instead of returning frame 0.
 paste handler hands the clipboard's own `File` straight to the upload path, and
 that path encodes `image/gif` and `image/webp` unchanged (`imageMediaType()`
 accepts both and returns them as-is) — no canvas, no `drawImage`, no `toBlob`.
-**The bytes reach the Host whole.** It is the Host that destroys them:
-`admitPromptContent` runs every image through the single-frame normalizer and
-keeps no copy of the source.
+**The bytes reach the Host whole.** The Host normalizes them through
+`attachments.saveImages`. In DSH 0.2.2 this happens during upload, so prompt
+admission receives an already-stored image reference.
 
-`admitPromptContent` is therefore the last moment the original bytes exist. The
-plugin wraps it, decodes the animation and stores the frames — then **returns the
-original result untouched**:
+The plugin wraps `saveImages`, captures the animation from its raw inputs, and
+stores the original and decoded frames against the returned image reference.
+This covers raw uploads and older encoded-prompt admission:
 
 ```
 you paste 1 animation
@@ -143,22 +143,26 @@ the gaps are gaps.
 
 ## Install
 
+Needs **DSH 0.1.3-alpha.2 or later** — see [COMPATIBILITY.md](COMPATIBILITY.md) for
+the measured range, how it was measured, and what is not claimed.
+
 ```sh
 dsh plugin --profile web add dsh-read-animation
 ```
 
-Replace `web` with your profile name. **Not on npm yet** — until it is, install
-straight from the repository:
+Replace `web` with your profile name. Both routes are verified in a real profile:
+the install lands, `dsh plugin add` registers the bundle, and the `sharp` native
+binary resolves from the package's own `node_modules`.
 
 ```sh
-dsh plugin --profile web add github:NeoHotaru/dsh-read-animation
+dsh plugin --profile web add dsh-read-animation                            # npm
+dsh plugin --profile web add github:NeoHotaru/dsh-read-animation#v0.1.0    # a tagged commit
 ```
 
-That route is verified end to end: it installs, `dsh plugin add` registers the
-bundle, and the `sharp` native binary resolves from the package's own
-`node_modules`. (A git spec copies the whole repository, tests and fixtures
-included, which is why the npm package above is the nicer install once it
-exists.)
+The git route copies the whole repository, tests and fixtures included, which is
+why npm is the nicer install. (A brand-new package name goes through npm's staged
+publishing on its first release, so the version you install may briefly not exist
+yet while the registry processes it.)
 
 Or from a checkout:
 
@@ -238,8 +242,8 @@ tool refuses to run when the resolved model route does not declare image input,
 for the same reason `read_image` does.
 
 **A pasted animation** is handled in three steps, none of which touch your
-message: **capture** at admission (`ctx.attachments.admitPromptContent` is the last
-moment the original bytes exist), **display** at `ctx.attachments.readImage` (the
+message: **capture** at image storage (`ctx.attachments.saveImages` receives the
+original bytes), **display** at `ctx.attachments.readImage` (the
 one read the UI makes, served the original so it plays), and **delivery** at
 `ctx.attachments.readImageRequest` (the model's copy, composed into one labelled
 sheet). All three are **monkey-patches of core service methods**, so they do

package/README.zh.md

@@ -47,10 +47,11 @@ APNG 得的是同一种病，而且更隐蔽：libvips 8.18.7 根本不认 `acTL
 **入口一 · 贴进聊天框。** 浏览器那段路本身是干净的——粘贴处理器把 `clipboardData` 里的原始
 `File` 直接交出去，上传路径对 `image/gif` / `image/webp` 原样编码（`imageMediaType()` 明确
 接受这两种并原样返回），没有 canvas、没有 `drawImage`、没有 `toBlob`。**字节完好地到达宿主。**
-丢掉它的是宿主自己：`admitPromptContent` 把每张图都过一遍「单帧」归一化，源字节不保留。
+宿主通过 `attachments.saveImages` 将图片归一化。DSH 0.2.2 在上传阶段就完成这一步，
+之后消息接收入口拿到的是已存储的图片引用。
 
-`admitPromptContent` 是**原件还存在的最后一刻**，所以本插件在这里把它解码、把帧存下来——
-然后**把原样的结果还回去**：
+本插件在 `saveImages` 保存图片时，用仍可访问的原始字节解码动画，并将原件和帧关联到
+返回的图片引用。这同时覆盖原始文件上传和旧版编码图片入口：
 
 ```
 你贴 1 张动图
@@ -121,15 +122,16 @@ frame 9 of 24 (sample 3) · starts at 450 ms · displayed for 50 ms
 dsh plugin --profile web add dsh-read-animation
 ```
 
-`web` 换成你自己的 profile 名。**目前还没发到 npm** —— 在那之前可以直接从仓库装：
+`web` 换成你自己的 profile 名。**两条路都在真实 profile 里验证过**：装得上、`dsh plugin add` 会把它
+注册成 bundle、`sharp` 的原生二进制也能从包自己的 `node_modules` 里解析出来。
 
 ```sh
-dsh plugin --profile web add github:NeoHotaru/dsh-read-animation
+dsh plugin --profile web add dsh-read-animation                            # npm
+dsh plugin --profile web add github:NeoHotaru/dsh-read-animation#v0.1.0    # 钉住某个 tag
 ```
 
-这条路是**实测过的**：能装上、`dsh plugin add` 会把它注册成 bundle、`sharp` 的原生二进制也能
-从包自己的 `node_modules` 里解析出来。（git spec 会把整个仓库连测试和 fixture 一起拷下来，
-所以等上面那个 npm 包存在之后，npm 那条路更干净。）
+git 那条会把整个仓库（含测试和 fixture）拷下来，所以 npm 更干净。（全新包名的**首次发布**会走
+npm 的 staged publishing，所以刚发完那一小段时间里，registry 上可能还查不到那个版本号。）
 
 或者从本地检出：
 
@@ -200,8 +202,8 @@ PNG，所以 harness 的归一化管线对它无事可做。
 `read_image` 完全一致。当解析出的模型路由未声明图片输入时，工具会拒绝执行——理由和
 `read_image` 相同。
 
-**贴进聊天框的动图**分三步，都不碰你的消息：**捕获**在准入层
-（`ctx.attachments.admitPromptContent` 是原件还在的最后一刻），**显示**在
+**贴进聊天框的动图**分三步，都不碰你的消息：**捕获**在图片存储层
+（`ctx.attachments.saveImages` 仍能访问上传原件），**显示**在
 `ctx.attachments.readImage`（界面取图的那一次读，返回原件所以会动），**交付**在
 `ctx.attachments.readImageRequest`（模型那份，拼成一张带标注的胶片条）。三步都是
 **猴补核心服务的方法**，所以写得很保守——

package/assets/icon.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="Four frames of one animation, with the subject growing across them">
+  <!--
+    The plugin's whole idea in one mark: one animation shown as a grid of frames
+    over time, with the subject changing across them.
+
+    Drawn for the size it is actually rendered at, roughly 40px on a bundle card:
+    four bold shapes, no gradients, no text, nothing that turns to mush. The
+    background is a mid-tone tile so the mark reads on both a light and a dark
+    card, and the frames inside carry the contrast.
+  -->
+  <rect width="96" height="96" rx="21" fill="#26333F"/>
+  <g fill="#EDF2F8">
+    <rect x="10" y="10" width="36" height="36" rx="7"/>
+    <rect x="50" y="10" width="36" height="36" rx="7"/>
+    <rect x="10" y="50" width="36" height="36" rx="7"/>
+    <rect x="50" y="50" width="36" height="36" rx="7"/>
+  </g>
+  <!--
+    The subject grows across the four moments. Size is a property the eye reads
+    even when it scans a grid out of order, which a position change is not: in a
+    2x2 layout, reading order jumps from the top right back to the bottom left, so
+    four dots each moving inside their own frame read as four unrelated things.
+  -->
+  <g fill="#26333F">
+    <circle cx="28" cy="28" r="5"/>
+    <circle cx="68" cy="28" r="7"/>
+    <circle cx="28" cy="68" r="9"/>
+  </g>
+  <!-- The last sampled moment is the one the sheet calls out, so it is the one
+       shape in the mark that is not greyscale. -->
+  <circle cx="68" cy="68" r="11" fill="#C9761B"/>
+</svg>