SITE KIT / 1.22.0

让页面提供内容,
让组件负责行为。

这是从原实验室提取的轻量建站入口,不导入250项案例目录、第三方引擎或演示主题。原250项保留为实验研究。当前5种组件可直接绑定你的网站已经输出的HTML。

独立入口与生命周期

<link rel="stylesheet" href="/site-kit/components.css">
<!-- 页面由你的网站或CMS输出,保留正文和真实链接。 -->
<header data-site-component="header" class="sk-header">
  <button data-menu-toggle aria-controls="my-nav">菜单</button>
  <nav id="my-nav"><a href="/products">产品</a></nav>
</header>
<!-- 在自己的外部模块脚本中: -->
import {mountSite, mountComponent} from '/site-kit/index.js';
import {createServices} from '/site-kit/services.js';
const services = createServices({
  endpoints: {inquiry: '/api/site-kit/inquiries'}
});
const site = mountSite({
  options: {form: {submit: services.submitInquiry,
    onSuccess: record => console.log(record.id)}}
});
// 路由离开或组件卸载时:
site.destroy();

mountSite按data-site-component寻找组件;导航、对话框、标签页立即绑定,显现与表单接近视口后载入。需要立即绑定时调用site.mount(element),或使用mountComponent(name, root, options)。mountComponent返回Promise,解析为带destroy方法的控制器。site.ready()等待当前正在挂载的组件,不会强制载入整页离屏内容。

常规组件只需components.css,外观由自己的网站定义。example.css仅用于验证页,不是必需主题。所有资源路径按示例部署在/site-kit/和/framework/下;移动目录时调整相对导入路径。原框架createMotion仍可用于实验或明确选择的效果,但正式页面优先使用独立入口。

5种组件及内容契约

header
已有header内提供data-menu-toggle按钮和nav。保留真实a[href],不会接管网站路由。可传onNavigate({href,label,event})与onMenuChange(open)。手机展开/收起与Esc关闭,桌面保持导航可见;destroy恢复初始状态。
reveal
容器中的data-scroll-reveal元素接受进入视口增强。支持duration、distance、stagger、reducedMotion;返回finish、replay、setReducedMotion、destroy。沿用原reading-motion算法,正文默认最终可见,减少动态、键盘聚焦和销毁时直接完成显示。
dialog
使用原生dialog,aria-labelledby指向页面已有标题;按钮data-site-open值为dialog的id,关闭按钮加data-site-close。支持onOpen/onClose、控制器open/close/destroy。原生模态隔离背景,显式Tab边界循环,Esc关闭、滚动锁定与焦点返回。页面重要内容不只放在弹窗中。
tabs
容器内提供role=tablist、role=tab、aria-controls和对应role=tabpanel。支持左右方向键、Home/End,onChange({index,id})。所有面板可先输出为可见HTML,绑定后才隐藏非当前面板;动态增加标签后应重新挂载。
form
绑定已有form及原生验证字段,必须传submit(values,{signal,key})。支持onSuccess、onError与messages;状态元素data-form-status,字段错误元素data-field-error对应name。提交中禁用提交按钮;取消、网络错误、超时和重试保留输入。成功必须由服务返回非空id与saved/accepted状态,不用计时器伪造。

业务服务契约与真实状态

createServices({endpoints,timeout,fetcher})返回submitInquiry、upload、getStock、saveCart、checkout、runAI和通用call。每个端点可以是URL,也可以是你自己的(payload,{signal,key})函数。URL默认POST,JSON数据用application/json;FormData保持multipart,不手工设置boundary。可用函数适配已有GET、认证、响应格式或流式接口;runAI默认只是一次HTTP调用,不自动提供SSE流处理。

未配置端点返回ServiceError(code=NOT_CONFIGURED),不生成假订单、假库存或假AI结果。标准响应为HTTP 2xx加{id,status:'saved'|'accepted'};错误用4xx/5xx加{code,message,fields:{字段名:说明}}。取消抛AbortError;超时返回TIMEOUT,网络失败返回NETWORK_ERROR。Idempotency-Key用于重试,服务端也必须实现去重;仅发送请求头不代表支付或订单已经具备幂等保障。

服务配置示例:createServices({endpoints:{inquiry:'/api/inquiries', checkout:async(payload,options)=>{ /* 调用并转换你的订单API */ }}})。不要把服务密钥写入前端;需要密钥的服务由自己后端调用。此项目没有接入任何支付、库存、实际AI供应商或邮件投递,亦未改变用户已有网站的业务收件人。

已提供的本机询盘后端

POST /api/site-kit/inquiries实际校验并保存name、email、message、company;支持JSON和原生表单编码,正文上限16KB。name为2–80字符、email最长254、message为10–3000字符。服务端对同一个Idempotency-Key和内容返回同一个记录id;同key内容不同返回409。JSONL记录在SITE_KIT_DATA_DIR/inquiries.jsonl,默认项目data/site-kit目录,不在public内,不提供公共记录查询。

服务返回status=saved表示记录已落盘,notification=not_configured表示未发送邮件,二者不可混称。该文件存储后端是本机集成参考,正式网站可替换为已有数据库、询盘系统与通知服务。线上部署时把SITE_KIT_DATA_DIR指向持久目录(例如/data/site-kit),保留原数据,不使用重置方式更新。独立包无外部依赖,Node≥20,npm start后访问/site-kit/example.html;PORT指定监听端口,监听0.0.0.0。先配置实际业务接口和访问策略,再用于公网业务。

性能与验收

原入口改为目录元数据与实现分离,各案例按需加载控制器、库和专用样式;底座示例不再串联导入全部提供器。普通文字使用系统字体;axes/wave才请求完整字形WOFF2(784500字节),原TTF保留作来源,未裁掉字形或字体轴。离屏引擎实例延迟销毁,最多保留6个;再次进入会重建,因此临时拖动/模拟状态会重置,速度、幅度和播放选择保留。模块代码缓存由浏览器管理,不宣称所有内存立即清零。

静态文本资源按Accept-Encoding提供Brotli/gzip,强ETag配合304;没有内容指纹的URL仍用no-cache重新校验,避免发布后长期读到旧代码。case-runtime暂停、隐藏、减少动态时取消帧循环,不再空跑RAF。按具体产品安排动效,导航、正文、提交和阅读不以动画结束为前提。

实际验证包含原250项载入、字体请求、真实开始/中间/结束状态、鼠标与触摸、键盘焦点、减少动态、无JS正文、表单错误/取消/重试、本机落盘、并发幂等、服务器重建读取、压缩与304、离屏回收和重入。没有实体手机或公网部署验收;尚未配置的业务不计作已完成。

研究、工作流与来源

本轮单一执行者Codex,无分派代理和独立评审。采用Refero设计检查流程;实时样式检索返回NO_SUBSCRIPTION,按现有实验室审计页视觉与随附motion/craft参考继续。验证页主色、系统字体、细边框和间距继承现有界面;新布局服务于内容、详情、提交与接口边界的验证。未复制外部产品图或字体,唯一示意图引用实验室原创scene-0.svg。

完整工具版本、逐模块来源、文件哈希、失败与修复及实测对比见release.json,原始证据与测试脚本在完整实验室源码包evidence/site-kit、tests/site-kit-*。独立组件包仅包含必要组件、共享阅读实现、验证页、询盘后端和API测试,排除本机数据记录及凭据。