liquidbook 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c2c697f9bb5b094c752a0798ef24b5bf0265f60c5ed490abe4b9ad2abbb2d60
-  data.tar.gz: dda835eaec1bef74610452dfe1596a1b517122ca9e66a852592aa5ca79a43700
+  metadata.gz: 0ff58ef9ec9c365f0d4d43ee4858493a3e8986a23ff705bef68c8a87ac2b6815
+  data.tar.gz: 6880caf5653cb43b33efbdf0438ecda8577d263bb827938344734a803a84e79e
 SHA512:
-  metadata.gz: a5ff5a395bdf717724ebec570cb4fb8ff039d4cd9940dbb2df6320e402e0ae18511d5ec2d1ebeca9f598b73f0b81cc96977bae7bcb996117fc0e07e8380d10ff
-  data.tar.gz: 731b75e5e253632d37d58033f49d12c4ef74820397212750174bc2e66b9d01c8ad980be48108197effefab90ec4009c6d57becd4b494793f17f0471659665efa
+  metadata.gz: 24a7f538b9a52aa7860fd172addf9c0c3cfbdfd244371b122c138240d08680750a108bc01802c2c0ea83235b624ba5a1fbd812991d9a617be6b4ee026f8d27c1
+  data.tar.gz: c2d92ed42b16be71375b8457896307d98e9a83ebfa28639dab13151d50718a4b69905ebdd18856593d91f0a91952e8264f1dab2e7ffebfdf79828e55d49cb7ac

data/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m ':*)",
+      "Bash(git push:*)",
+      "WebFetch(domain:guides.rubygems.org)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(*--force*push*)",
+      "Bash(*push --force*)",
+      "Bash(*push -f*)",
+      "Bash(curl:*)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)"
+    ]
+  }
+}

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-03
+
+### Added
+
+- `TemplateAnalyzer`: Liquid AST を走査してテンプレートで参照される変数を自動検出（[ADR-0001](docs/adr/0001-template-variable-detection-strategy.md)）
+- `ParameterMerger`: 自動検出した変数と `@param` メタデータをマージして `ThemeRenderer` に統合
+- `FilterTypeMap` によるフィルタベースの型推論（適用されているフィルタ名から変数の型を推定）
+- サイドバーにテンプレート検索窓を追加（`q` URL パラメータで画面遷移後も検索状態を保持）
+- サイドバー初期表示時にアクティブなテンプレートまで自動スクロール
+- 動作確認用 `example/` テーマ（`bundle exec liquidbook server -r example` で起動）
+- ADR-0001: テンプレート変数検出戦略の決定記録
+
+### Changed
+
+- カスタム `RenderTag` を削除し公式 Liquid `render` タグ + `ThemeFileSystem` に置き換え（探索対象を `snippets/` のみに限定し、`ThemeRenderer` で `ThemeFileSystem` をキャッシュ）
+- スニペットパラメータ編集フォームを GET + クエリパラメータ方式に変更し、URL でプレビュー状態をブックマーク/共有可能に（`Rendered HTML` ビューも同期）
+- `example/` ディレクトリを gem パッケージから除外
+
+### Removed
+
+- `POST /api/render/:type/:name` および `GET /api/render/:type/:name` エンドポイント、および 1.5 秒間隔のライブリロードポーリング
+
+## [0.1.1] - 2026-04-09
+
+### Added
+
+- グレースフルなサーバー停止のための PID ファイル管理と `stop` コマンド
+- CD ワークフロー: タグ push 時に CHANGELOG から GitHub Release を自動生成
+- CD ワークフロー: `workflow_dispatch` による RubyGems への手動公開
+
+### Changed
+
+- CI ワークフローのファイル名を `test.yml` から `ci.yml` にリネーム
+
+## [0.1.0] - 2026-04-07
+
+### Added
+
+- モックデータをサポートする Liquid テンプレートレンダリングエンジン
+- Sinatra によるブラウザベースのプレビューサーバー
+- Thor による CLI コマンド (`start`, `stop`)
+- Listen による自動リロード対応のファイル監視
+- セクション/スニペットテンプレートのサポート
+- RSpec によるユニットテストと統合テスト
+- GitHub Actions による CI パイプライン (Ruby 3.2 - 4.0)

data/CLAUDE.md

@@ -0,0 +1,17 @@
+# CLAUDE.md
+
+## コーディング方針
+
+- コードを変更・追加するとき、設計判断の「なぜ（Why）」が自明でなければコメントを残す
+  - 「何をしているか（What）」はコードで表現する。コメントにしない
+  - 例: Shopify 互換性のために本来不要な処理をしている、パフォーマンス上の理由で構造を変えた、等
+
+## プロジェクト概要
+
+- Shopify Liquid テンプレートのプレビューサーバー（Storybook 的なツール）
+- Ruby gem（Liquid 5.0 / Sinatra / Puma）
+
+## 開発コマンド
+
+- テスト: `bundle exec rspec`
+- サーバー起動: `bundle exec liquidbook serve`

data/README.md

@@ -1,6 +1,6 @@
 # Liquidbook
 
-[![CI](https://github.com/sena-m09/liquidbook/actions/workflows/test.yml/badge.svg)](https://github.com/sena-m09/liquidbook/actions/workflows/test.yml)
+[![CI](https://github.com/sena-m09/liquidbook/actions/workflows/ci.yml/badge.svg)](https://github.com/sena-m09/liquidbook/actions/workflows/ci.yml)
 
 A Storybook-like local preview server for Shopify Liquid templates. Browse and preview your sections and snippets in the browser instantly.
 
@@ -78,6 +78,14 @@ cd liquidbook
 bin/setup
 ```
 
+Run the preview server against the bundled example theme:
+
+```bash
+bundle exec liquidbook server -r example
+```
+
+See [Release Process](docs/RELEASING.md) for how to publish a new version.
+
 ## License
 
 [MIT License](https://opensource.org/licenses/MIT)

data/docs/README.ja.md

@@ -76,6 +76,8 @@ cd liquidbook
 bin/setup
 ```
 
+新しいバージョンのリリース方法は [Release Process](RELEASING.md) を参照してください。
+
 ## ライセンス
 
 [MIT License](https://opensource.org/licenses/MIT)

data/docs/RELEASING.md

@@ -0,0 +1,51 @@
+# Release Process
+
+## CI/CD ワークフロー構成
+
+| ワークフロー | ファイル | トリガー | 内容 |
+|---|---|---|---|
+| CI | `ci.yml` | push (main) / PR | テスト実行 (Ruby 3.2 - 4.0) |
+| GitHub Release | `github_release.yml` | `v*` タグ push | CHANGELOG から抽出 → GitHub Release 作成 |
+| RubyGems 公開 | `gem_release.yml` | 手動 (`workflow_dispatch`) | RubyGems に gem push |
+
+## リリース手順
+
+### 1. バージョンと CHANGELOG を更新
+
+`lib/liquidbook/version.rb` のバージョンを更新:
+
+```ruby
+VERSION = "X.Y.Z"
+```
+
+`CHANGELOG.md` に変更内容を追記（`[Unreleased]` から新バージョンのセクションへ移動）:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- ...
+```
+
+### 2. コミットしてタグを打つ
+
+```bash
+git add lib/liquidbook/version.rb CHANGELOG.md
+git commit -m "chore: bump version to X.Y.Z"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+### 3. GitHub Release を確認
+
+タグ push をトリガーに GitHub Release が自動作成されます。CHANGELOG から該当バージョンのノートが抽出されます。
+
+[Actions > Create GitHub Release](https://github.com/sena-m09/liquidbook/actions/workflows/github_release.yml) で結果を確認してください。
+
+### 4. RubyGems に公開
+
+GitHub Release の内容を確認した後、手動で gem を公開します:
+
+[Actions > Publish to RubyGems](https://github.com/sena-m09/liquidbook/actions/workflows/gem_release.yml) → "Run workflow" を実行
+
+> gem push を手動トリガーにしているのは、公開前に最終確認できるようにするためです。

data/docs/adr/0001-template-variable-detection-strategy.md

@@ -0,0 +1,69 @@
+# ADR-0001: テンプレート変数検出の戦略
+
+- **Status**: Accepted
+- **Date**: 2026-04-21
+- **Deciders**: @sena-m09
+
+## Context
+
+Liquidbook はテンプレートのプレビューに必要な変数（パラメータ）を知る必要がある。
+現在は2つの方法で宣言的に定義している:
+
+- **sections**: `{% schema %}` ブロック内の JSON で `settings` / `blocks` を定義（Shopify 公式仕様）
+- **snippets**: `@param` JSDoc 風コメントで型・デフォルト値・説明を記述
+
+この方式には以下の課題がある:
+
+1. `@param` を書かない snippet は変数が一切検出されず、プレビューフォームが空になる
+2. 宣言と実際のテンプレート使用が乖離しても検知できない（書き忘れ、削除忘れ）
+3. Storybook のような別ファイル方式（`.stories.yml`）の導入も検討したが、Liquid テンプレートの規模感では管理コストが過剰
+
+## Decision
+
+**Liquid AST からの変数自動検出を基盤とし、`@param` / `{% schema %}` を補足情報として重ねる方式（方式2）を採用する。**
+
+### 具体的な構成
+
+```
+TemplateAnalyzer (AST 変数抽出)
+       |
+       v
+自動検出された変数: [title, price, featured]
+       |
+       v
+ParamParser / SchemaParser (型・デフォルト値・説明をマージ)
+       |
+       v
+最終結果: [title: String "My Card", price: Number 1980, featured: Boolean false]
+```
+
+- `TemplateAnalyzer` が `Liquid::Template.parse` の AST を走査し、外部依存変数を抽出する
+- ループ変数（`for item in ...` の `item`）や `assign` のローカル変数は自動除外する
+- `section.settings.*` / `section.blocks` は schema 由来として分類する
+- `@param` が存在する変数には型・デフォルト値・説明を上書きマージする
+- `@param` がない変数も「unknown 型」としてプレビューフォームに表示する
+
+## Alternatives Considered
+
+### 方式1: 自動検出のみ（宣言ファイル不要）
+
+- メリット: 何も書かなくていい
+- デメリット: 型推論に限界がある（`title` が String か Number かは AST からは判断できない）、デフォルト値や説明を付けられない
+- 判断: 自動検出だけでは UI の品質が不十分
+
+### 方式3: 別ファイル（Storybook 式 `.stories.yml`）
+
+- メリット: テンプレートが汚れない、variants を複数定義できる
+- デメリット: ファイル管理コスト、テンプレートとの sync 切れリスク
+- 判断: コンポーネント数が数百規模のプロジェクト向け。Liquid テンプレートの規模感では過剰
+
+### 方式2 から方式3 への移行可能性
+
+方式3 に移行する場合でも、TemplateAnalyzer は「`.stories.yml` に書き忘れた変数を警告する」用途でそのまま活用できる。TemplateAnalyzer の実装は無駄にならない。
+
+## Consequences
+
+- `TemplateAnalyzer` を新規作成する（Liquid AST 走査）
+- `ParamParser` は TemplateAnalyzer の結果に型情報をマージする役割に変わる
+- `@param` なしの snippet でもプレビューフォームが自動生成される
+- 将来的に `@param` の文法拡張（複合型など）を行う場合、ParamParser の書き換えが必要になるが、TemplateAnalyzer とは独立している

data/lib/liquidbook/filter_type_map.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Liquidbook
+  # Maps Liquid filter names to inferred parameter types.
+  # Used by ParameterMerger as a fallback when @param annotations are absent.
+  #
+  # Type names match ParamParser's normalized types: "text", "number", "checkbox".
+  module FilterTypeMap
+    FILTER_TYPES = {
+      # Numeric filters
+      "money" => "number",
+      "money_with_currency" => "number",
+      "plus" => "number",
+      "minus" => "number",
+      "times" => "number",
+      "divided_by" => "number",
+      "modulo" => "number",
+      "round" => "number",
+      "ceil" => "number",
+      "floor" => "number",
+      "abs" => "number",
+      "at_least" => "number",
+      "at_most" => "number",
+      # Text filters
+      "upcase" => "text",
+      "downcase" => "text",
+      "capitalize" => "text",
+      "strip" => "text",
+      "lstrip" => "text",
+      "rstrip" => "text",
+      "strip_html" => "text",
+      "strip_newlines" => "text",
+      "newline_to_br" => "text",
+      "escape" => "text",
+      "escape_once" => "text",
+      "url_encode" => "text",
+      "url_decode" => "text",
+      "truncate" => "text",
+      "truncatewords" => "text",
+      "append" => "text",
+      "prepend" => "text",
+      "remove" => "text",
+      "remove_first" => "text",
+      "replace" => "text",
+      "replace_first" => "text",
+      "split" => "text",
+      "handle" => "text",
+      "handleize" => "text",
+      "md5" => "text",
+      "sha1" => "text",
+      "sha256" => "text",
+      "base64_encode" => "text",
+      "base64_decode" => "text"
+    }.freeze
+
+    # Infer a type from a list of filter names.
+    # Returns the type if all filters agree, nil if ambiguous or no filters match.
+    def self.infer(filters)
+      types = filters.filter_map { |f| FILTER_TYPES[f] }.uniq
+      types.size == 1 ? types.first : nil
+    end
+  end
+end

data/lib/liquidbook/parameter_merger.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Liquidbook
+  # Merges auto-detected template variables (from TemplateAnalyzer) with
+  # type/default/description metadata from @param comments (ParamParser).
+  #
+  # Variables with @param get their declared type/default/description.
+  # Variables without @param are type-inferred from filters and control structures
+  # (e.g. money → number, for-loop → array, truthy if → checkbox).
+  # When inference is inconclusive, type falls back to "unknown".
+  # Section variables (name == "section") are excluded.
+  #
+  # Usage:
+  #   merger = ParameterMerger.new(
+  #     variables:  analyzer.external_variables,
+  #     param_defs: param_parser.parse
+  #   )
+  #   merger.merge
+  #   # => [{ "name" => "title", "type" => "text", "default" => "My Card", "description" => "Card heading" },
+  #   #     { "name" => "color", "type" => "unknown", "default" => nil, "description" => nil }]
+  class ParameterMerger
+    def initialize(variables:, param_defs:)
+      @variables  = variables
+      @param_defs = param_defs
+    end
+
+    def merge
+      @variables
+        .reject { |var| section_variable?(var) }
+        .map { |var| resolve(var) }
+        .uniq { |p| p["name"] }
+    end
+
+    private
+
+    def resolve(var)
+      name = var[:name].to_s
+      param_index[name] || inferred(var)
+    end
+
+    def param_index
+      @param_index ||= @param_defs.each_with_object({}) do |p, h|
+        h[p["name"]] = p
+      end
+    end
+
+    def section_variable?(var)
+      var[:name].to_s == "section"
+    end
+
+    def inferred(var)
+      name = var[:name].to_s
+      type = infer_type(var)
+      { "name" => name, "type" => type, "default" => nil, "description" => nil }
+    end
+
+    def infer_type(var)
+      properties = var[:properties] || []
+
+      return "array" if properties.any? { |p| p[:collection] }
+      return "checkbox" if properties.any? { |p| p[:truthy_condition] } && all_filters_empty?(properties)
+
+      all_filters = properties.flat_map { |p| p[:filters] }.uniq
+      FilterTypeMap.infer(all_filters) || "unknown"
+    end
+
+    def all_filters_empty?(properties)
+      properties.all? { |p| p[:filters].empty? }
+    end
+  end
+end

data/lib/liquidbook/server/app.rb

@@ -1,14 +1,21 @@
 # frozen_string_literal: true
 
 require "sinatra/base"
-require "json"
 
 module Liquidbook
   module Server
     class App < Sinatra::Base
+      RESERVED_QUERY_KEYS = %w[name splat captures q].freeze
+
       set :views, File.expand_path("views", __dir__)
       set :public_folder, -> { File.join(Liquidbook.root, "assets") }
 
+      before do
+        @nav_sections = ThemeRenderer.new(theme_root: Liquidbook.root).sections
+        @nav_snippets = ThemeRenderer.new(theme_root: Liquidbook.root).snippets
+        @current_path = request.path_info
+      end
+
       helpers do
         def renderer
           @renderer ||= ThemeRenderer.new(theme_root: Liquidbook.root)
@@ -43,7 +50,6 @@ module Liquidbook
           @name = name
           @type = "section"
           @schema = load_schema("sections", name)
-          @params = []
           erb :preview
         rescue Liquidbook::Error => e
           status 404
@@ -55,12 +61,13 @@ module Liquidbook
       get "/snippets/:name" do
         name = params[:name]
         begin
-          overrides = parse_overrides(params)
+          @form_params = renderer.snippet_params(name)
+          overrides = parse_overrides(params, @form_params)
           @rendered = renderer.render_snippet(name, overrides: overrides)
           @name = name
           @type = "snippet"
           @schema = {}
-          @params = renderer.snippet_params(name)
+          @form_params = with_overrides_applied(@form_params, overrides)
           erb :preview
         rescue Liquidbook::Error => e
           status 404
@@ -94,47 +101,6 @@ module Liquidbook
         end
       end
 
-      # API: re-render with params (for live reload + param editing)
-      post "/api/render/:type/:name" do
-        content_type :json
-        type = params[:type]
-        name = params[:name]
-
-        begin
-          body = JSON.parse(request.body.read) rescue {}
-          overrides = body["overrides"] || {}
-
-          html = case type
-                 when "sections" then renderer.render_section(name, overrides: overrides)
-                 when "snippets" then renderer.render_snippet(name, overrides: overrides)
-                 else raise Error, "Unknown type: #{type}"
-                 end
-          { html: html }.to_json
-        rescue Liquidbook::Error => e
-          status 404
-          { error: e.message }.to_json
-        end
-      end
-
-      # API: re-render (GET for live reload)
-      get "/api/render/:type/:name" do
-        content_type :json
-        type = params[:type]
-        name = params[:name]
-
-        begin
-          html = case type
-                 when "sections" then renderer.render_section(name)
-                 when "snippets" then renderer.render_snippet(name)
-                 else raise Error, "Unknown type: #{type}"
-                 end
-          { html: html }.to_json
-        rescue Liquidbook::Error => e
-          status 404
-          { error: e.message }.to_json
-        end
-      end
-
       private
 
       def load_schema(dir, name)
@@ -144,15 +110,57 @@ module Liquidbook
         SchemaParser.new(File.read(path)).parse
       end
 
-      def parse_overrides(params)
+      # Build override hash from query params, coercing types based on @param metadata.
+      # Strings (including Japanese / multibyte) pass through as Rack-decoded UTF-8.
+      def parse_overrides(params, params_meta = nil)
+        type_by_name = build_type_index(params_meta)
         overrides = {}
+
         params.each do |key, value|
-          next if %w[name splat captures].include?(key)
+          next if RESERVED_QUERY_KEYS.include?(key)
 
-          overrides[key] = value
+          overrides[key] = coerce_override(value, type_by_name[key])
         end
+
         overrides
       end
+
+      def build_type_index(params_meta)
+        return {} unless params_meta
+
+        params_meta.each_with_object({}) { |p, h| h[p["name"]] = p["type"] }
+      end
+
+      def coerce_override(value, type)
+        case type
+        when "checkbox" then value.to_s == "true"
+        when "number" then coerce_number(value)
+        else value
+        end
+      end
+
+      def coerce_number(value)
+        str = value.to_s.strip
+        return str if str.empty?
+
+        Integer(str, 10)
+      rescue ArgumentError
+        begin
+          Float(str)
+        rescue ArgumentError
+          str
+        end
+      end
+
+      # Return a new params_meta list with each param's "default" replaced by the
+      # current override value, so the form re-renders with submitted values.
+      # Non-destructive: original hashes are preserved (snippet_params caching-safe).
+      def with_overrides_applied(params_meta, overrides)
+        params_meta.map do |p|
+          name = p["name"]
+          overrides.key?(name) ? p.merge("default" => overrides[name]) : p
+        end
+      end
     end
   end
 end

data/lib/liquidbook/server/views/index.erb

@@ -1,16 +1,28 @@
+<style>
+  .lp-card {
+    display: block;
+    padding: 16px;
+    background: var(--lp-surface);
+    border: 1px solid var(--lp-border);
+    border-radius: var(--lp-radius);
+    text-decoration: none;
+    color: var(--lp-text);
+    transition: border-color 0.2s;
+  }
+  .lp-card:hover {
+    border-color: var(--lp-accent);
+  }
+</style>
+
 <h2 style="margin-bottom: 16px; font-size: 20px;">Sections</h2>
 <% if @sections.empty? %>
-  <p style="color: var(--text-sub);">No sections found in <code>sections/</code></p>
+  <p style="color: var(--lp-text-sub);">No sections found in <code>sections/</code></p>
 <% else %>
   <div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 12px; margin-bottom: 32px;">
     <% @sections.each do |name| %>
-      <a href="/sections/<%= h(name) %>" style="
-        display: block; padding: 16px; background: var(--surface);
-        border: 1px solid var(--border); border-radius: var(--radius);
-        text-decoration: none; color: var(--text); transition: border-color 0.2s;
-      " onmouseover="this.style.borderColor='var(--accent)'" onmouseout="this.style.borderColor='var(--border)'">
+      <a href="/sections/<%= h(name) %>" class="lp-card">
         <div style="font-weight: 500;"><%= h(name) %></div>
-        <div style="font-size: 12px; color: var(--text-sub); margin-top: 4px;">section</div>
+        <div style="font-size: 12px; color: var(--lp-text-sub); margin-top: 4px;">section</div>
       </a>
     <% end %>
   </div>
@@ -18,17 +30,13 @@
 
 <h2 style="margin-bottom: 16px; font-size: 20px;">Snippets</h2>
 <% if @snippets.empty? %>
-  <p style="color: var(--text-sub);">No snippets found in <code>snippets/</code></p>
+  <p style="color: var(--lp-text-sub);">No snippets found in <code>snippets/</code></p>
 <% else %>
   <div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 12px;">
     <% @snippets.each do |name| %>
-      <a href="/snippets/<%= h(name) %>" style="
-        display: block; padding: 16px; background: var(--surface);
-        border: 1px solid var(--border); border-radius: var(--radius);
-        text-decoration: none; color: var(--text); transition: border-color 0.2s;
-      " onmouseover="this.style.borderColor='var(--accent)'" onmouseout="this.style.borderColor='var(--border)'">
+      <a href="/snippets/<%= h(name) %>" class="lp-card">
         <div style="font-weight: 500;"><%= h(name) %></div>
-        <div style="font-size: 12px; color: var(--text-sub); margin-top: 4px;">snippet</div>
+        <div style="font-size: 12px; color: var(--lp-text-sub); margin-top: 4px;">snippet</div>
       </a>
     <% end %>
   </div>

data/lib/liquidbook/server/views/layout.erb

@@ -14,46 +14,205 @@
       --lp-accent: #5c6ac4;
       --lp-border: #e0e0e0;
       --lp-radius: 8px;
+      --lp-sidebar-w: 240px;
+      --lp-topbar-h: 48px;
     }
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: var(--lp-bg);
+      color: var(--lp-text);
+    }
+
+    /* ── Topbar ── */
     .lp-topbar {
       background: var(--lp-surface);
       border-bottom: 1px solid var(--lp-border);
-      padding: 12px 24px;
+      padding: 0 20px;
+      height: var(--lp-topbar-h);
       display: flex;
       align-items: center;
       gap: 16px;
-      position: sticky;
+      position: fixed;
       top: 0;
-      z-index: 10000;
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      left: 0;
+      right: 0;
+      z-index: 100;
     }
     .lp-topbar h1 {
-      font-size: 16px;
-      font-weight: 600;
+      font-size: 15px;
+      font-weight: 700;
       color: var(--lp-accent);
-      margin: 0;
     }
-    .lp-topbar nav a {
+    .lp-topbar h1 a {
+      color: inherit;
+      text-decoration: none;
+    }
+
+    /* ── Sidebar ── */
+    .lp-sidebar {
+      position: fixed;
+      top: var(--lp-topbar-h);
+      left: 0;
+      bottom: 0;
+      width: var(--lp-sidebar-w);
+      background: var(--lp-surface);
+      border-right: 1px solid var(--lp-border);
+      overflow-y: auto;
+      padding: 16px 0;
+      font-size: 13px;
+    }
+    .lp-sidebar-group {
+      margin-bottom: 8px;
+    }
+    .lp-sidebar-heading {
+      padding: 4px 16px;
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
       color: var(--lp-text-sub);
+    }
+    .lp-sidebar-item {
+      display: block;
+      padding: 6px 16px 6px 24px;
+      color: var(--lp-text);
       text-decoration: none;
-      font-size: 14px;
+      border-left: 3px solid transparent;
+      transition: background 0.15s, border-color 0.15s;
     }
-    .lp-topbar nav a:hover { color: var(--lp-accent); }
-    .lp-container {
-      max-width: 1200px;
-      margin: 0 auto;
+    .lp-sidebar-item[hidden] {
+      display: none;
+    }
+    .lp-sidebar-item:hover {
+      background: var(--lp-bg);
+    }
+    .lp-sidebar-item.active {
+      background: var(--lp-bg);
+      border-left-color: var(--lp-accent);
+      color: var(--lp-accent);
+      font-weight: 500;
+    }
+    .lp-sidebar-empty {
+      padding: 6px 16px 6px 24px;
+      color: var(--lp-text-sub);
+      font-style: italic;
+    }
+    .lp-sidebar-search {
+      padding: 8px 12px 12px;
+    }
+    .lp-sidebar-search-input {
+      width: 100%;
+      padding: 6px 8px;
+      border: 1px solid var(--lp-border);
+      border-radius: 4px;
+      font-size: 13px;
+      font-family: inherit;
+    }
+    .lp-sidebar-search-input:focus-visible {
+      border-color: var(--lp-accent);
+      outline: 2px solid var(--lp-accent);
+      outline-offset: -1px;
+    }
+
+    /* ── Main ── */
+    .lp-main {
+      margin-left: var(--lp-sidebar-w);
+      margin-top: var(--lp-topbar-h);
       padding: 24px;
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      min-height: calc(100vh - var(--lp-topbar-h));
     }
   </style>
 </head>
 <body>
   <div class="lp-topbar">
-    <h1>Liquidbook</h1>
-    <nav><a href="/">Home</a></nav>
+    <h1><a href="/">Liquidbook</a></h1>
   </div>
-  <div class="lp-container">
+
+  <nav class="lp-sidebar">
+    <div class="lp-sidebar-search">
+      <input type="text" class="lp-sidebar-search-input" placeholder="テンプレートを検索">
+    </div>
+    <div class="lp-sidebar-group">
+      <div class="lp-sidebar-heading">Sections</div>
+      <% if @nav_sections.empty? %>
+        <div class="lp-sidebar-empty">No sections</div>
+      <% else %>
+        <% @nav_sections.each do |name| %>
+          <a href="/sections/<%= h(name) %>"
+             class="lp-sidebar-item<%= ' active' if @current_path == "/sections/#{name}" %>">
+            <%= h(name) %>
+          </a>
+        <% end %>
+      <% end %>
+    </div>
+    <div class="lp-sidebar-group">
+      <div class="lp-sidebar-heading">Snippets</div>
+      <% if @nav_snippets.empty? %>
+        <div class="lp-sidebar-empty">No snippets</div>
+      <% else %>
+        <% @nav_snippets.each do |name| %>
+          <a href="/snippets/<%= h(name) %>"
+             class="lp-sidebar-item<%= ' active' if @current_path == "/snippets/#{name}" %>">
+            <%= h(name) %>
+          </a>
+        <% end %>
+      <% end %>
+    </div>
+  </nav>
+
+  <main class="lp-main">
     <%= yield %>
-  </div>
+  </main>
+  <script>
+    (function() {
+      const input = document.querySelector('.lp-sidebar-search-input');
+      const links = document.querySelectorAll('.lp-sidebar-item');
+
+      function filterSidebar(query) {
+        document.querySelectorAll('.lp-sidebar-group').forEach(function(group) {
+          const items = group.querySelectorAll('.lp-sidebar-item');
+          if (items.length === 0) return;
+          let visibleCount = 0;
+          items.forEach(function(item) {
+            const match = item.textContent.toLowerCase().includes(query);
+            item.hidden = !match;
+            if (match) visibleCount++;
+          });
+          group.hidden = visibleCount === 0;
+        });
+      }
+
+      function updateLinks(value) {
+        links.forEach(function(a) {
+          const url = new URL(a.href);
+          if (value) {
+            url.searchParams.set('q', value);
+          } else {
+            url.searchParams.delete('q');
+          }
+          a.href = url;
+        });
+      }
+
+      input.addEventListener('input', function() {
+        filterSidebar(this.value.toLowerCase());
+        updateLinks(this.value);
+      });
+
+      var q = new URLSearchParams(location.search).get('q');
+      if (q) {
+        input.value = q;
+        filterSidebar(q.toLowerCase());
+        updateLinks(q);
+      }
+
+      const active = document.querySelector('.lp-sidebar-item.active');
+      if (active) {
+        const sidebar = document.querySelector('.lp-sidebar');
+        sidebar.scrollTop = active.offsetTop;
+      }
+    })();
+  </script>
 </body>
 </html>

data/lib/liquidbook/server/views/preview.erb

@@ -38,22 +38,32 @@
   <div style="width: 320px; flex-shrink: 0; position: sticky; top: 64px;">
 
     <!-- Snippet @param editor -->
-    <% if @params && !@params.empty? %>
+    <% if @form_params && !@form_params.empty? %>
       <div style="background: var(--lp-surface); border: 1px solid var(--lp-border); border-radius: var(--lp-radius); padding: 16px; margin-bottom: 16px;">
         <h3 style="font-size: 14px; margin: 0 0 12px; color: var(--lp-text-sub);">Parameters</h3>
-        <form id="param-form">
-          <% @params.each do |param| %>
+        <form method="get" action="/snippets/<%= h(@name) %>" accept-charset="UTF-8">
+          <% if (sidebar_q = request.params["q"]) && !sidebar_q.empty? %>
+            <input type="hidden" name="q" value="<%= h(sidebar_q) %>">
+          <% end %>
+          <% @form_params.each do |param| %>
             <div style="margin-bottom: 12px;">
               <label style="display: block; font-size: 12px; font-weight: 500; margin-bottom: 4px;">
                 <%= h(param["name"]) %>
                 <span style="font-weight: normal; color: var(--lp-text-sub);"><%= h(param["description"]) %></span>
               </label>
               <% if param["type"] == "checkbox" %>
-                <input type="checkbox" name="<%= h(param["name"]) %>" <%= "checked" if param["default"] %> data-param>
+                <div style="display: flex; gap: 12px; font-size: 13px;">
+                  <label style="display: flex; align-items: center; gap: 4px;">
+                    <input type="radio" name="<%= h(param["name"]) %>" value="true" <%= "checked" if param["default"] %>> Yes
+                  </label>
+                  <label style="display: flex; align-items: center; gap: 4px;">
+                    <input type="radio" name="<%= h(param["name"]) %>" value="false" <%= "checked" unless param["default"] %>> No
+                  </label>
+                </div>
               <% elsif param["type"] == "number" %>
-                <input type="number" name="<%= h(param["name"]) %>" value="<%= h(param["default"]) %>" style="width: 100%; padding: 6px 8px; border: 1px solid var(--lp-border); border-radius: 4px; font-size: 13px;" data-param>
+                <input type="number" name="<%= h(param["name"]) %>" value="<%= h(param["default"]) %>" style="width: 100%; padding: 6px 8px; border: 1px solid var(--lp-border); border-radius: 4px; font-size: 13px;">
               <% else %>
-                <input type="text" name="<%= h(param["name"]) %>" value="<%= h(param["default"]) %>" style="width: 100%; padding: 6px 8px; border: 1px solid var(--lp-border); border-radius: 4px; font-size: 13px;" data-param>
+                <input type="text" name="<%= h(param["name"]) %>" value="<%= h(param["default"]) %>" style="width: 100%; padding: 6px 8px; border: 1px solid var(--lp-border); border-radius: 4px; font-size: 13px;">
               <% end %>
             </div>
           <% end %>
@@ -128,56 +138,4 @@
   function setWidth(w) {
     document.getElementById('preview-frame').style.maxWidth = w;
   }
-
-  // Param form → re-render via POST
-  const form = document.getElementById('param-form');
-  if (form) {
-    form.addEventListener('submit', async (e) => {
-      e.preventDefault();
-      const overrides = {};
-      form.querySelectorAll('[data-param]').forEach(el => {
-        if (el.type === 'checkbox') {
-          overrides[el.name] = el.checked;
-        } else if (el.type === 'number') {
-          overrides[el.name] = Number(el.value);
-        } else {
-          overrides[el.name] = el.value;
-        }
-      });
-
-      const type = '<%= @type == "section" ? "sections" : "snippets" %>';
-      const name = '<%= @name %>';
-      try {
-        const res = await fetch(`/api/render/${type}/${name}`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ overrides })
-        });
-        const data = await res.json();
-        if (data.html) {
-          document.getElementById('preview-frame').innerHTML = data.html;
-        }
-      } catch (err) {
-        console.error('Render error:', err);
-      }
-    });
-  }
-
-  // Live reload via polling (file changes)
-  (function() {
-    const type = '<%= @type == "section" ? "sections" : "snippets" %>';
-    const name = '<%= @name %>';
-    let lastHtml = null;
-
-    setInterval(async () => {
-      try {
-        const res = await fetch(`/api/render/${type}/${name}`);
-        const data = await res.json();
-        if (data.html && lastHtml !== null && data.html !== lastHtml) {
-          document.getElementById('preview-frame').innerHTML = data.html;
-        }
-        lastHtml = data.html;
-      } catch (e) {}
-    }, 1500);
-  })();
 </script>

data/lib/liquidbook/template_analyzer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Liquidbook
+  # Analyzes Liquid templates by walking the AST to detect external variable dependencies.
+  #
+  # Usage:
+  #   analyzer = TemplateAnalyzer.new(template_source)
+  #   analyzer.external_variables
+  #   # => [{ name: "title", properties: [{ lookups: [], filters: ["upcase"] }] },
+  #   #     { name: "product", properties: [{ lookups: ["name"], filters: ["money"] }] }]
+  class TemplateAnalyzer
+    def initialize(source)
+      @source = source
+    end
+
+    def external_variables
+      clean_source = strip_schema(@source)
+      template = Liquid::Template.parse(clean_source)
+      vars = {}
+      scope = Scope.new
+
+      template.root.nodelist&.each { |node| walk(node, vars, scope) }
+
+      vars.values
+    end
+
+    def section_variable?(var)
+      var[:name] == "section"
+    end
+
+    private
+
+    # Tracks local variables with proper scoping for for-loops.
+    # Uses a parent chain so child scopes see parent locals,
+    # while scoped variables (loop vars) don't leak upward.
+    class Scope
+      def initialize(parent = nil)
+        @parent = parent
+        @locals = []
+      end
+
+      def add_local(name)
+        @locals << name
+      end
+
+      def local?(name)
+        @locals.include?(name) || @parent&.local?(name) || false
+      end
+
+      def child_with(extra_locals)
+        child = Scope.new(self)
+        extra_locals.each { |l| child.add_local(l) }
+        child
+      end
+    end
+
+    SCHEMA_REGEX = /\{%-?\s*schema\s*-?%\}.*?\{%-?\s*endschema\s*-?%\}/m
+
+    def strip_schema(source)
+      source.gsub(SCHEMA_REGEX, "")
+    end
+
+    def walk(node, vars, scope)
+      case node
+      when Liquid::Variable
+        collect_variable(node, vars, scope)
+      when Liquid::For
+        walk_for(node, vars, scope)
+        return
+      when Liquid::Assign
+        scope.add_local(node.instance_variable_get(:@to).to_s)
+      when Liquid::Capture
+        scope.add_local(node.instance_variable_get(:@to).to_s)
+      when Liquid::If
+        walk_if(node, vars, scope)
+        return
+      end
+
+      walk_nodelist(node, vars, scope)
+    end
+
+    def walk_for(node, vars, scope)
+      coll = node.collection_name
+      add_lookup(vars, coll, scope, collection: true) if coll.is_a?(Liquid::VariableLookup)
+
+      inner_scope = scope.child_with([node.variable_name, "forloop"])
+      node.nodelist&.each { |child| walk(child, vars, inner_scope) }
+
+      else_block = node.instance_variable_get(:@else_block)
+      else_block&.nodelist&.each { |child| walk(child, vars, scope) }
+    end
+
+    def walk_if(node, vars, scope)
+      node.blocks.each do |condition|
+        walk_condition(condition, vars, scope)
+        condition.attachment&.nodelist&.each { |child| walk(child, vars, scope) }
+      end
+    end
+
+    def walk_condition(condition, vars, scope)
+      return unless condition
+
+      left = condition.left
+      right = condition.right
+      operator = condition.instance_variable_get(:@operator)
+      truthy = left.is_a?(Liquid::VariableLookup) && operator.nil? && right.nil?
+
+      add_lookup(vars, left, scope, truthy_condition: truthy) if left.is_a?(Liquid::VariableLookup)
+      add_lookup(vars, right, scope) if right.is_a?(Liquid::VariableLookup)
+
+      child = condition.child_condition
+      walk_condition(child, vars, scope) if child
+    end
+
+    def collect_variable(node, vars, scope)
+      vl = node.is_a?(Liquid::Variable) ? node.name : nil
+      if vl.is_a?(Liquid::VariableLookup)
+        filters = node.filters&.map { |name, _, _| name } || []
+        add_lookup(vars, vl, scope, filters: filters)
+      end
+
+      return unless node.is_a?(Liquid::Variable)
+
+      node.filters&.each do |_name, args, kwargs|
+        args&.each { |a| add_lookup(vars, a, scope) if a.is_a?(Liquid::VariableLookup) }
+        kwargs&.each_value { |v| add_lookup(vars, v, scope) if v.is_a?(Liquid::VariableLookup) }
+      end
+    end
+
+    def add_lookup(vars, lookup, scope, filters: [], collection: false, truthy_condition: false)
+      return unless lookup.is_a?(Liquid::VariableLookup)
+      return if scope.local?(lookup.name)
+
+      key = lookup.name
+      vars[key] ||= { name: key, properties: [] }
+
+      prop = vars[key][:properties].find { |p| p[:lookups] == lookup.lookups }
+      unless prop
+        prop = { lookups: lookup.lookups, filters: [] }
+        vars[key][:properties] << prop
+      end
+
+      prop[:filters].concat(filters)
+      prop[:filters].uniq!
+      prop[:collection] = true if collection
+      prop[:truthy_condition] = true if truthy_condition
+    end
+
+    def walk_nodelist(node, vars, scope)
+      return unless node.respond_to?(:nodelist)
+
+      node.nodelist&.each { |child| walk(child, vars, scope) }
+    end
+  end
+end

data/lib/liquidbook/theme_file_system.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Liquidbook
+  # FileSystem implementation for Liquid's render tag.
+  # Resolves template names by searching snippets/ directory.
+  class ThemeFileSystem
+    VALID_NAME = /\A[a-zA-Z0-9_-]+\z/
+
+    def initialize(theme_root)
+      @theme_root = theme_root
+    end
+
+    def read_template_file(template_name)
+      raise Liquid::FileSystemError, "Illegal template name '#{template_name}'" unless VALID_NAME.match?(template_name)
+
+      path = full_path(template_name)
+      raise Liquid::FileSystemError, "No such template '#{template_name}'" unless path
+
+      File.read(path)
+    end
+
+    private
+
+    def full_path(template_name)
+      path = File.join(@theme_root, "snippets", "#{template_name}.liquid")
+      path if File.exist?(path)
+    end
+  end
+end

data/lib/liquidbook/theme_renderer.rb

@@ -46,16 +46,20 @@ module Liquidbook
       template = Liquid::Template.parse(template_source, environment: Liquidbook.environment)
       template.render(
         assigns,
-        registers: { theme_root: @theme_root }
+        registers: {
+          theme_root: @theme_root,
+          file_system: theme_file_system
+        }
       )
     end
 
-    # Extract @param definitions from a snippet
+    # Extract merged parameter definitions for a snippet.
+    # Combines TemplateAnalyzer auto-detected variables with @param metadata.
     def snippet_params(name)
       path = File.join(@theme_root, "snippets", "#{name}.liquid")
       return [] unless File.exist?(path)
 
-      ParamParser.new(File.read(path)).parse
+      merged_params(File.read(path))
     end
 
     # List available sections
@@ -71,7 +75,21 @@ module Liquidbook
     private
 
     def snippet_defaults(source)
-      ParamParser.new(source).default_assigns
+      merged_params(source).each_with_object({}) do |param, hash|
+        next if param["type"] == "unknown"
+
+        hash[param["name"]] = param["default"]
+      end
+    end
+
+    def merged_params(source)
+      variables  = TemplateAnalyzer.new(source).external_variables
+      param_defs = ParamParser.new(source).parse
+      ParameterMerger.new(variables: variables, param_defs: param_defs).merge
+    end
+
+    def theme_file_system
+      @theme_file_system ||= ThemeFileSystem.new(@theme_root)
     end
 
     def list_templates(dir)

data/lib/liquidbook/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Liquidbook
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/liquidbook.rb

@@ -5,10 +5,13 @@ require_relative "liquidbook/version"
 require_relative "liquidbook/config"
 require_relative "liquidbook/schema_parser"
 require_relative "liquidbook/param_parser"
+require_relative "liquidbook/template_analyzer"
+require_relative "liquidbook/filter_type_map"
+require_relative "liquidbook/parameter_merger"
 require_relative "liquidbook/mock_data"
 require_relative "liquidbook/filters/shopify_filters"
 require_relative "liquidbook/tags/section_tag"
-require_relative "liquidbook/tags/render_tag"
+require_relative "liquidbook/theme_file_system"
 require_relative "liquidbook/pid_manager"
 require_relative "liquidbook/theme_renderer"
 require_relative "liquidbook/server/app"
@@ -43,7 +46,6 @@ module Liquidbook
       Liquid::Environment.build do |e|
         e.register_filter(Filters::ShopifyFilters)
         e.register_tag("section", Tags::SectionTag)
-        e.register_tag("render", Tags::RenderTag)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liquidbook
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - sena-m09
@@ -102,27 +102,35 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/settings.json"
 - ".rspec"
+- CHANGELOG.md
+- CLAUDE.md
 - LICENSE
 - README.md
 - Rakefile
 - docs/README.ja.md
+- docs/RELEASING.md
+- docs/adr/0001-template-variable-detection-strategy.md
 - exe/liquidbook
 - fixtures/default_mocks.yml
 - lib/liquidbook.rb
 - lib/liquidbook/cli.rb
 - lib/liquidbook/config.rb
+- lib/liquidbook/filter_type_map.rb
 - lib/liquidbook/filters/shopify_filters.rb
 - lib/liquidbook/mock_data.rb
 - lib/liquidbook/param_parser.rb
+- lib/liquidbook/parameter_merger.rb
 - lib/liquidbook/pid_manager.rb
 - lib/liquidbook/schema_parser.rb
 - lib/liquidbook/server/app.rb
 - lib/liquidbook/server/views/index.erb
 - lib/liquidbook/server/views/layout.erb
 - lib/liquidbook/server/views/preview.erb
-- lib/liquidbook/tags/render_tag.rb
 - lib/liquidbook/tags/section_tag.rb
+- lib/liquidbook/template_analyzer.rb
+- lib/liquidbook/theme_file_system.rb
 - lib/liquidbook/theme_renderer.rb
 - lib/liquidbook/version.rb
 - sig/liquidbook.rbs
@@ -147,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Storybook-like preview server for Shopify Liquid sections and snippets
 test_files: []

data/lib/liquidbook/tags/render_tag.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Liquidbook
-  module Tags
-    # Handles {% render 'snippet' %} and {% render 'snippet' with object %}
-    # Also handles {% render 'snippet' for collection %}
-    class RenderTag < Liquid::Tag
-      SYNTAX = /['"]([^'"]+)['"](?:\s+(?:with|for)\s+(\S+)(?:\s+as\s+(\w+))?)?/
-
-      def initialize(tag_name, markup, tokens)
-        super
-        if markup.strip =~ SYNTAX
-          @snippet_name = Regexp.last_match(1)
-          @variable_expr = Regexp.last_match(2)
-          @alias_name = Regexp.last_match(3)
-        else
-          # Try simple variable assignments: {% render 'snippet', var: value %}
-          if markup.strip =~ /['"]([^'"]+)['"]\s*,?\s*(.*)/
-            @snippet_name = Regexp.last_match(1)
-            @inline_vars = parse_inline_vars(Regexp.last_match(2))
-          else
-            raise Liquid::SyntaxError, "Invalid syntax for render tag: #{markup}"
-          end
-        end
-      end
-
-      def render(context)
-        theme_root = context.registers[:theme_root] || Liquidbook.root
-        snippet_path = find_snippet(theme_root)
-
-        unless snippet_path
-          return "<!-- snippet '#{@snippet_name}' not found -->"
-        end
-
-        source = File.read(snippet_path)
-        template = Liquid::Template.parse(source, environment: Liquidbook.environment)
-
-        # Build isolated scope
-        inner = {}
-
-        if @variable_expr
-          value = context[@variable_expr]
-          alias_key = @alias_name || @snippet_name
-          inner[alias_key] = value
-        end
-
-        if @inline_vars
-          @inline_vars.each do |key, expr|
-            inner[key] = context[expr] || expr
-          end
-        end
-
-        # Merge parent assigns with inner scope
-        parent_assigns = {}
-        context.environments.each { |env| parent_assigns.merge!(env) if env.is_a?(Hash) }
-        assigns = parent_assigns.merge(inner)
-
-        template.render(
-          assigns,
-          registers: { theme_root: theme_root }
-        )
-      end
-
-      private
-
-      def find_snippet(theme_root)
-        paths = [
-          File.join(theme_root, "snippets", "#{@snippet_name}.liquid"),
-          File.join(theme_root, "sections", "#{@snippet_name}.liquid")
-        ]
-        paths.find { |p| File.exist?(p) }
-      end
-
-      def parse_inline_vars(str)
-        return {} if str.nil? || str.strip.empty?
-
-        vars = {}
-        str.scan(/(\w+)\s*:\s*([^,]+)/) do |key, value|
-          vars[key.strip] = value.strip.gsub(/\A['"]|['"]\z/, "")
-        end
-        vars
-      end
-    end
-  end
-end