make-tweakable

Make Tweakable

在现有 HTML 成品中注入一个浮动的 Tweaks 面板。面板位于成品内部（不使用 iframe），使用 File System Access API 持久化（并提供复制粘贴备用方案）。

模式

1. 在 :root 中使用 --tweak- 前缀的 CSS 自定义属性封装可调整的默认值
2. 添加标记块 <script id="__tweak_schema" type="application/json">{...}</script>，其中包含默认值
3. 注入浮动面板（<div id="tweaks-panel">），并为每个键绑定控件
4. 面板通过 File System Access API 将更新写入 pending.yaml（首次使用时会请用户选择目标文件）
5. 按 Shift+T 切换面板显示状态
6. 用户运行 /apply-tweaks <html-path> 或说“保存调整”——Claude 读取 pending.yaml，使用 Edit 工具编辑 HTML，并清空待处理内容

阶段 1 — 确定键

如果用户指定了键（$ARGUMENTS），则使用这些键。否则根据成品推断：

• 颜色（primaryColor、accentColor、bgColor、textColor）
• 字体排版（fontFamily、fontSize、lineHeight）
• 间距（gap、padding）
• 布局变体（dense/comfortable/spacious）
• 深色模式开关

保持精简——设置 4-7 个选项，而不是 20 个。

阶段 2 — 重构 HTML，使用 --tweak- 变量

对于每个键，在 HTML 中查找硬编码值，并替换为 var(--tweak-keyName)。在 :root 上设置默认值：

:root {
  --tweak-primaryColor: #D97757;
  --tweak-fontSize: 16px;
  --tweak-density: 1;  /* multiplier */
}

添加 schema 块：

<script id="__tweak_schema" type="application/json">
{
  "primaryColor": { "type": "color", "default": "#D97757" },
  "fontSize": { "type": "number", "default": 16, "min": 12, "max": 32, "step": 1, "unit": "px" },
  "density": { "type": "number", "default": 1, "min": 0.75, "max": 1.5, "step": 0.05 },
  "dark": { "type": "boolean", "default": false }
}
</script>

阶段 3 — 注入 Tweaks 面板

在 </body> 前追加：

<script>
(async () => {
  const schemaEl = document.getElementById('__tweak_schema');
  if (!schemaEl) return;
  const schema = JSON.parse(schemaEl.textContent);
  const values = Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, v.default]));

  // Restore from localStorage for in-browser state
  const lsKey = '__tweaks_' + location.pathname;
  try { Object.assign(values, JSON.parse(localStorage.getItem(lsKey) || '{}')); } catch {}

  const panel = document.createElement('div');
  panel.id = 'tweaks-panel';
  panel.hidden = true;
  panel.style.cssText = `
    position: fixed; right: 16px; bottom: 16px; z-index: 99999;
    font: 13px/1.4 ui-sans-serif, system-ui;
    background: #fff; color: #111;
    border: 1px solid #ddd; border-radius: 10px;
    padding: 14px; min-width: 240px;
    box-shadow: 0 8px 24px rgba(0,0,0,0.12);
  `;

  const applyValues = () => {
    const root = document.documentElement;
    for (const [k, v] of Object.entries(values)) {
      const meta = schema[k];
      if (meta.type === 'color' || meta.type === 'string') root.style.setProperty('--tweak-' + k, v);
      else if (meta.type === 'number') root.style.setProperty('--tweak-' + k, v + (meta.unit || ''));
      else if (meta.type === 'boolean') root.classList.toggle('tweak-' + k, !!v);
    }
    try { localStorage.setItem(lsKey, JSON.stringify(values)); } catch {}
  };

  const header = document.createElement('div');
  header.style.cssText = 'font-weight:600;margin-bottom:10px;display:flex;justify-content:space-between;align-items:center';
  header.innerHTML = `<span>Tweaks</span><span style="opacity:0.5;font-weight:400;font-size:11px">Shift+T to toggle</span>`;
  panel.appendChild(header);

  for (const [key, meta] of Object.entries(schema)) {
    const row = document.createElement('label');
    row.style.cssText = 'display:flex;justify-content:space-between;align-items:center;gap:12px;margin:8px 0';
    const label = document.createElement('span');
    label.textContent = key;
    label.style.cssText = 'font-family:ui-monospace,Menlo;font-size:11px;opacity:0.7';
    row.appendChild(label);

    let input;
    if (meta.type === 'color') {
      input = document.createElement('input');
      input.type = 'color';
      input.value = values[key];
    } else if (meta.type === 'number') {
      input = document.createElement('input');
      input.type = 'range';
      input.min = meta.min; input.max = meta.max; input.step = meta.step;
      input.value = values[key];
      input.style.width = '100px';
    } else if (meta.type === 'boolean') {
      input = document.createElement('input');
      input.type = 'checkbox';
      input.checked = !!values[key];
    } else {
      input = document.createElement('input');
      input.type = 'text';
      input.value = values[key];
    }
    input.addEventListener('input', () => {
      values[key] = meta.type === 'boolean' ? input.checked :
                    meta.type === 'number' ? Number(input.value) : input.value;
      applyValues();
      scheduleWrite();
    });
    row.appendChild(input);
    panel.appendChild(row);
  }

  // Persistence buttons
  const actions = document.createElement('div');
  actions.style.cssText = 'display:flex;gap:6px;margin-top:10px;padding-top:10px;border-top:1px solid #eee';
  const linkBtn = document.createElement('button');
  linkBtn.textContent = 'Link pending.yaml';
  linkBtn.style.cssText = 'flex:1;padding:6px 8px;font-size:11px;background:#f5f5f5;border:1px solid #ddd;border-radius:4px;cursor:pointer';
  const copyBtn = document.createElement('button');
  copyBtn.textContent = 'Copy YAML';
  copyBtn.style.cssText = linkBtn.style.cssText;
  actions.appendChild(linkBtn);
  actions.appendChild(copyBtn);
  panel.appendChild(actions);

  const status = document.createElement('div');
  status.style.cssText = 'margin-top:8px;font-size:10px;color:#888';
  status.textContent = 'Not persisted';
  panel.appendChild(status);

  let fsHandle = null;
  let writeTimer = null;
  const yamlFor = (v) => Object.entries(v).map(([k,val]) => `${k}: ${JSON.stringify(val)}`).join('\n') + '\n';
  const scheduleWrite = () => {
    if (!fsHandle) return;
    clearTimeout(writeTimer);
    writeTimer = setTimeout(async () => {
      try {
        const w = await fsHandle.createWritable();
        await w.write(yamlFor(values));
        await w.close();
        status.textContent = 'Written to pending.yaml @ ' + new Date().toLocaleTimeString();
      } catch (e) {
        status.textContent = 'Write failed: ' + e.message;
      }
    }, 300);
  };

  linkBtn.addEventListener('click', async () => {
    if (!window.showSaveFilePicker) {
      status.textContent = 'File System Access API not available — use Copy YAML instead';
      return;
    }
    try {
      fsHandle = await window.showSaveFilePicker({
        suggestedName: 'pending.yaml',
        types: [{ description: 'YAML', accept: { 'text/yaml': ['.yaml'] } }],
      });
      status.textContent = 'Linked. Writing live.';
      scheduleWrite();
    } catch (e) {
      status.textContent = 'Link cancelled';
    }
  });

  copyBtn.addEventListener('click', async () => {
    try {
      await navigator.clipboard.writeText(yamlFor(values));
      status.textContent = 'Copied YAML to clipboard. Paste to Claude and say "apply tweaks"';
    } catch (e) {
      status.textContent = 'Copy failed: ' + e.message;
    }
  });

  document.body.appendChild(panel);
  applyValues();

  window.addEventListener('keydown', (e) => {
    if (e.shiftKey && (e.key === 'T' || e.key === 't')) {
      panel.hidden = !panel.hidden;
    }
  });
})();
</script>

阶段 4 — 会话状态文件

Bash(mkdir -p artifacts/tweaks/<session-id>/applied)
Write artifacts/tweaks/<session-id>/state.yaml:
  target_html: <path>
  phase: idle
  last_applied_at: null

session-id = tweaks-{slug}-{YYYYMMDD}。

向用户回复：“已启用 Tweaks。在预览中按 Shift+T 打开。点击 ‘Link pending.yaml’ → 选择 artifacts/tweaks/<session-id>/pending.yaml——面板现在会在每次更改时实时写入。满意后，说 ‘应用调整’ 或运行 /apply-tweaks <html-path>。”

阶段 5 — 验证

运行 /serve（成品使用外部 .jsx 启动模板时需要），然后运行 /done http://127.0.0.1:4567/<html-path> → 确认面板显示、Shift+T 可切换，且控制台无错误。

持久化说明： File System Access API 需要 http 源（Chrome >= 2024 中在 file:// 上也可用，但存在一些限制）。建议始终通过 http 提供可调整的成品。