Archify 分享即演示基于?play1#view单章自动播放契约的可验证图表分享设计【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify导读本文围绕 Archify仓库路径GitHub_Trending/arch/archify第 14 轮视觉演化Visual evolution round 14的核心成果展开一个名为 Share-ready one-shot chapters分享即用的单次播放章节的 viewer-only 分享契约。它用?play1#viewid一段 URL让读者打开链接即可看到某个已存在视图只播放一次、随后定格为静态图的完整演示而不是再引入一套新的动画系统。读完本文你将掌握该契约的 URL 语义、data-autoplay状态机的五个取值、无障碍与prefers-reduced-motion的处理方式以及源码与测试如何约束这套行为。一、问题背景共享链接为什么只展示静态帧在引入本契约之前Archify 已经具备两项能力具名视图深链可以通过#viewid深链到某一个已命名的引导视图手动完整故事播放用户可以通过 Story Trail 手动播放一整个完整的引导故事guided story。但这两个能力组合起来存在明显的体验缺口一个被分享出去的#viewURL 打开后停留在静态帧上——读者看不到任何演示动作落地页landing page的证明选择器proof selector问题更严重它链接指向的是引导视图的名称但嵌入的工件embedded artifact实际加载的是通用完整图两者语义不一致环境痕迹循环ambient trace loops的问题在于一个证明网格proof grid在已经传达完信息之后可能还在持续不断地运动干扰阅读。因此产品真正需要的不是又一套动画系统而是一个紧凑的show me this chapter给我展示这一章契约。这一判断也决定了后续所有设计取舍的基调动画要有明确的主体subject、明确的生命周期lifetime并且最终要把控制权交还给读者handoff back to the reader。二、借鉴的行业模式与设计边界2.1 三个方向的参考Fireworks Tech Graph证明先展示运动、再解释内容具有营销价值同时也印证了运动必须有一个清晰的视觉主体而不是一堆同时发生的效果叠加。React Flow 的动画边示例把动画绑定到真实的、计算出的路径上同时让动画生命周期与路径计算解耦。Archify 延续了这一分离Story Trail 负责查看器内的运动类型化渲染器typed renderers只负责几何编译。这一分工在渲染器目录renderers下的 architecture、workflow、sequence、dataflow、lifecycle 五个子目录中得到体现。WCAG 2.2.2Pause, Stop, Hide自动启动且持续超过 5 秒的移动内容必须提供暂停/停止/隐藏机制。一个 3.2 秒的单章播放低于该边界播放结束后留下稳定的静态阅读表面因此不需要额外的暂停按钮。MDN 的prefers-reduced-motion与matchMedia()分别提供 CSS 侧与 JavaScript 侧读取操作系统减少动态效果偏好reduce-motion的方式。2.2 最终借鉴的结论可借鉴的是带明确主体、明确生命周期、并交还控制权给读者的运动而不是动画本身。三、核心契约?play1#viewid的语义定义Archify 的决定是把?play1#viewid定义为仅查看器生效viewer-only的分享契约源码中由 assets/template.html 统一承载3.1 契约的七条规则哈希只选择已有的作者视图#viewid必须对应一个已存在的具名视图authored view不会发明新的拓扑或章节只播放该章节一次使用既有 3.2 秒视图间隔VIEW_INTERVAL_MS 3200见 template.html 源码中var VIEW_INTERVAL_MS 3200播放完毕后绝不自动切换到下一个视图无#view时播放第一个作者视图且不重写 URL即?play1单独使用时播放首个视图但不通过history.replaceState改写地址prefers-reduced-motion: reduce时保留所选视图与可读的 Story Trail但抑制自动运动节点点击、视图切换、缩放、平移、移动端滑动、文档隐藏、或手动暂停立即把控制权交还给读者data-autoplaypending|playing|complete|interrupted|reduced-motion使生命周期可被检查inspectable而不引入新的 UI 或 schema 状态嵌入模式与?play1分享模式都会暂停环境痕迹循环ambient trace loops。3.2 不同场景下的使用方式场景URL 形态行为图库预览gallery preview普通嵌入 iframe保持静态不自动播放落地页单章演示一个 iframe 嵌入?play1#viewid只播放一个具名章节直接证明动作direct proof action?present1play1#view...结合演示模式与单章播放README 动效展示捕获同一个#view具名章节 URL不再依赖无关的连续 trace 循环也就是说环境痕迹动画只在读者主动启动完整故事时恢复。3.3 不变式渲染管线零改动本契约不改变以下任何内容类型化 JSONtyped JSON渲染出的 SVG 几何rendered SVG geometry作者标记与样式authored markers/styles规范导出canonical exports这保证了分享契约是纯查看器行为五个类型化渲染器architecture / workflow / sequence / dataflow / lifecycle产出的 SVG 与导出文件完全不受影响。四、源码级实现状态机、分享提示条与运动闸门4.1data-autoplay五态状态机源码 assets/template.html 中以setAutoplayState(state)维护面板上的data-autoplay属性五态分别是pending检测到?play1尚未开始播放autoplayPending sharePlaybackRequested()成立时置位playing当前章节正在播放中complete单章播放自然结束pausePlayback({ complete: true })interrupted被用户操作打断节点点击、缩放、平移、手动暂停等reduced-motion用户系统开启了减少动态效果自动运动被抑制。这五个状态通过 CSS 属性选择器即可被样式层观察同时renderShareCue()会将其翻译为可读文案如 ready / playing / settled / paused / still写入分享提示条share cue。4.2 URL 解析与播放范围// 摘自 archify/assets/template.html示意行号以仓库为准 function sharePlaybackRequested() { try { return new URLSearchParams(location.search).get(play) 1; } catch (_) { return false; } } autoplayPending sharePlaybackRequested(); if (autoplayPending) { document.documentElement.setAttribute(data-share-playback, true); setAutoplayState(pending); }play1解析失败非法的location.search时安全降级为falsestartCurrentViewPlayback()将storyPlaybackScope置为chapter并调用setAutoplayState(playing)finishStoryChapter()中当storyPlaybackScope chapter时调用pausePlayback({ complete: true })不进入下一个视图——这正是one-shot chapter的代码级保证maybeStartSharePlayback()在document.hidden文档被隐藏/切后台时拒绝启动。4.3 运动闸门什么时候不允许自动播放function storyAutomaticPlaybackAllowed() { if (document.hidden || reducedMotion()) return false; if (window.matchMedia window.matchMedia(print).matches) return false; if (Archify.motionGovernor Archify.motionGovernor.capable) return !Archify.motionGovernor.isPaused(); return true; }自动播放的允许条件包含四重检查文档可见、系统未开启 reduce-motion、非打印环境、motionGovernor 未暂停。同时storyMotionAllowed()还额外要求data-motionlive且嵌入模式data-embedtrue下必须带有data-share-playbacktrue——即嵌入 iframe 里只有显式?play1的分享场景才能出现动画载体carrier。4.4 分享提示条Share Cue与进度条当data-embedtrue且data-share-playbacktrue或钉住章节data-share-momenttrue时renderShareCue()渲染一个share-chapter-cue提示条包含章节序号如01 / 03与视图名当前状态文案shareCueStatus节拍文案shareCueBeatCopy播放中显示第 03/07 步标签完成时显示共 7 步路由摘要stops 数组拼接的→/←/↔路线进度条动画archify-guided-progress时长以VIEW_INTERVAL_MS为准。shareCue.setAttribute(aria-live, state playing ? off : polite);播放进行中aria-live关闭以避免刷屏朗读播放结束或被打断时恢复polite——兼顾了屏幕阅读器的可访问性。4.5 环境痕迹循环的暂停模板中html[data-share-playbacktrue] svg[data-animationtrace] [data-animate]规则在分享播放期间暂停 trace 动画嵌入与分享模式下Archify.motionGovernor也会因为html.hasAttribute(data-embed) || html.hasAttribute(data-share-playback)而拒绝其他动画抢占。这就是图库预览保持静态、只有显式?play1的 iframe 才演示一章的实现依据。4.6 URL 只读策略function updateUrl(view) { try { history.replaceState(null, , location.pathname location.search (view ? #view encodeURIComponent(view.id) : )); } catch (_) {} }?play1单独使用时通过activate(0, { playback: true, updateUrl: false })播放第一个视图但不改写 URL只有显式选择视图时才写入#view。history.replaceState的失败被try/catch吞掉保证隐私模式下也安全降级。五、测试如何锁定契约行为仓库中的 story-carrier.test.mjs 用 Node 内置node:test驱动五个真实渲染器编译示例工件再对产物 HTML 做断言覆盖了本契约的关键行为only explicit play1 embeds may show the finite carrier断言模板同时包含data-embed true document.documentElement.getAttribute(data-share-playback) ! true嵌入且非分享播放时禁止运动autoplayPending sharePlaybackRequested()play1的解析入口document.documentElement.setAttribute(data-share-playback, true)分享播放标记html[data-motionstill] .story-carrier-overlay与html[data-document-hiddentrue] .story-carrier-overlay静止与隐藏文档时隐藏载体media (prefers-reduced-motion: reduce)下.story-carrier-overlay { display: none !important; }系统减动效时彻底隐藏载体。all five renderers inherit one viewer-only Semantic Story Carrier五种类型architecture / workflow / sequence / dataflow / lifecycle的产物都含story-flow-token与data-story-carrier-token但规范化后的canonicalSvg()中绝不出现这些 token——证明动画载体属于查看器层永远不会污染 SVG 几何与导出文件。Story reuses the exact semantic token vocabulary on its existing finite edge pulse载体动画是**有限次finite**的——assert.doesNotMatch(template, /story-flow-token[^}]infinite/)明确断言不存在 infinite 无限循环动画从测试层面杜绝了网格永远动下去的旧问题。清理与导出归属载体 overlay 由 Story Trail 持有并清理overlay.remove()、clearStoryPulse()media print下 overlay 全部隐藏导出克隆时会剔除[data-story-overlay], [data-story-carrier-overlay]。此外guided-views.test.mjs、gallery.test.mjs、proof-aperture.test.mjs、landing.test.mjs 与 readme-showcase.test.mjs 均引用了?play1相关断言分别锁定图库、证明选择器、落地页与 README 展示场景下分享播放的行为边界。六、明确不做的事设计边界Archify 在取舍中明确拒绝了以下行为以保证契约的克制的分享演示定位不为所有图库卡片自动播放不引入滚动触发时间线scroll-triggered timelines不让分享章节循环播放looped shared chapters不自动前进隐藏的轮播auto-advance hidden carousel不引入动画 schemaanimation schema。手动 Play 始终是完整的全故事的唯一有意识入口分享自动播放是一次有边界的演示 随后的静态图。也就是说?play1是营销意义上的电梯演讲Manual Play 才是完整的深度讲解两者职责互不重叠。七、接入与验证方式该契约是查看器viewer内建能力无需额外 schema 或配置即可使用在落地页/README 中嵌入演示为 iframe 指定?play1#view已有视图 id并确保 HTML 根元素带data-embedtrue直接打开演示在浏览器地址栏访问?present1play1#viewid进入演示单章自动播放图库保持静态默认嵌入无?play1即为静态帧环境痕迹动画被暂停无障碍校验在操作系统开启减少动态效果后打开同一 URL应看到所选视图与可读的 Story Trail、进度条直接定格reduced-motion状态载体 overlay 不渲染回归验证运行 run-tests.mjs 中的story-carrier测试组确认play1分享载体只出现在显式分享场景、且 SVG 导出不被污染。仓库内可直接查看的参考产物包括 workflow-agent-tool-call-rendered.html、lifecycle-agent-run.html、sequence-cache-miss-request.html、dataflow-product-analytics.html 与 web-app-rendered.html它们均由各自的类型化渲染器编译可作为?play1契约的实测载体相关设计历史可回看 research-fireworks-tech-graph.md 以及 research-visual-evolution-round-13.md第 14 轮的前一轮演化记录。总结?play1#view是 Archify 在分享体验上的一个克制的工程答案用纯查看器层的 URL 契约 五态可检查状态机 有限次动画载体在不改动类型化 JSON、SVG 几何与规范导出的前提下把一个具名章节演示一次、随后定格交还控制权做成了可分享、可无障碍访问、可被测试锁定的产品能力。它没有发明新的动画系统却解决了共享链接停留在静态帧、证明网格无限运动、落地页嵌入语义错位这三个真实问题——这正是少即是多在图表分享场景下的具体实践。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考