poetry-extract 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed76ffcd49da0ac979971eeef72b4c0a97be11697ffa2ffe550c5ae48e1692ff
-  data.tar.gz: fb3b471179c0e6c9cc02a483bc4079dbbd2a24589e94f63c11a0e82810ca22c3
+  metadata.gz: 5109279ef95e4b1b84d54d211de9c092e5ef5853fb543ec13aab67c438212a3c
+  data.tar.gz: 5e5518b6a7ceed15536bb7f6998d8c53ddadc6f023cce646118ccd76701e61be
 SHA512:
-  metadata.gz: 39deed401d146e53a7af84c722aa8320ac0ecc27fcbffb25245026161300e0f9ad671a38035ad8fa0d49f7ac7766c35e076dcfba6be5dec9895034f00ab7a393
-  data.tar.gz: cc808e8c66da94c0529b47a053c81627965ab977927917578860df3a3972ee407eaf6a0eda4764f5554ef1bdc03a52ae5fc7269b88422b4c6824496b27df65f0
+  metadata.gz: b1678f0845188edcc2a4e3ca02cd692e2ed883dd32cdd9bdee63fe7e3c5dfbdeffeb1994f06b293036b44a3b97a613b85fe6204e90ea0d93577272251c506b41
+  data.tar.gz: 05de37f2f6d66ad3693fd3d471c3f6e5ccfee7befb538d4b973e118383c0761881458f489ab8a9f08735d9e3ebea98de90064b211283b7e57a368872632763c6

data/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "rubydex": {
+      "command": "bundle",
+      "args": ["exec", "rdx", "mcp"]
+    }
+  }
+}

data/.yard-lint.yml

@@ -0,0 +1,25 @@
+# yard-lint: the documentation tier YARD's own gates miss - a documented
+# method missing a @param, an @example that does not parse, option tags,
+# tag order, invalid types. Runs as rake yard:lint (in the default task).
+# UndocumentedObjects stays off: yard:coverage gates public objects at its
+# recorded floor, and this validator counts the @api private internals the
+# gems hide on purpose (--hide-api is not honoured here). MissingReturn is
+# off until the @param backlog is cleared; revisit then.
+AllValidators:
+  YardOptions:
+    - --no-private
+Documentation/UndocumentedObjects:
+  Enabled: false
+Documentation/MissingReturn:
+  Enabled: false
+Tags/InvalidTypes:
+  Enabled: true
+# A **options splat passed through to a control is documented as @param
+# options [Hash], not one @option per key; and @example blocks here are
+# ERB as often as Ruby, which this validator cannot parse.
+Documentation/UndocumentedOptions:
+  Enabled: false
+Tags/OptionTags:
+  Enabled: false
+Tags/ExampleSyntax:
+  Enabled: false

data/.yard_coverage_all

@@ -0,0 +1 @@
+0

data/Archspec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The architecture the family enforces by review, as checks (rake arch:check).
+# extract depends on core alone.
+root "."
+source "lib/**/*.rb"
+
+component :lib, in: "lib/**/*.rb"
+
+lib.cannot_reference_constants "Poetry::Ui", "Poetry::Charts", "Poetry::Agent", "ApplicationController",
+                               because: "extract depends on core alone and never names the host"

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.5] - 2026-09-18
+
+### Changed
+
+- 43 methods the reference already hid with `@api private` are Ruby-private now: each was called only by its own class or template, so the runtime enforces what the tag only stated. A host that reached one gets a NoMethodError instead of an internal that may change without notice. The tag remains on the internals the family shares between its gems and on whole internal classes.
+- Every class, module and method carries a one-sentence description, private helpers included: `rake yard:coverage:all` measures the whole tree (a tag-only docstring counts as blank) and the committed floor now stands at zero.
+- The palette builder reads its sources, chooses its roles, builds the chart series and writes the hash in separate steps; the oracle parity suite holds every output byte for byte, and two tests pin that a primary already on the right side of its canvas is left alone in the derived mode.
+
+## [0.1.4] - 2026-09-15
+
+Lockstep release with the family; no changes in this gem.
+
 ## [0.1.3] - 2026-09-13
 
 Lockstep release with the family; no changes in this gem.

data/lib/poetry/extract/compose.rb

@@ -110,15 +110,12 @@ module Poetry
       end
 
       # A Messages API text content block.
-      # @api private
       def text_block(text) = { type: "text", text: text }
 
       # A Messages API URL-source image content block.
-      # @api private
       def image_block(url) = { type: "image", source: { type: "url", url: url } }
 
       # Join the response's text blocks into one string.
-      # @api private
       def extract_text(response)
         Array(response["content"]).filter_map { |block| block["text"] if block["type"] == "text" }.join
       end
@@ -144,6 +141,8 @@ module Poetry
 
         JSON.parse(response.body)
       end
+
+      private_class_method :text_block, :image_block, :extract_text
     end
   end
 end

data/lib/poetry/extract/derive_tokens.rb

@@ -23,6 +23,12 @@ module Poetry
     module DeriveTokens
       WHITE = { r: 255.0, g: 255.0, b: 255.0 }.freeze
       BLACK = { r: 0.0, g: 0.0, b: 0.0 }.freeze
+      # The dark mode canvas.
+      DARK_BACKGROUND = { r: 23.0, g: 23.0, b: 21.0 }.freeze
+      # The light mode text color.
+      LIGHT_FOREGROUND = { r: 10.0, g: 10.0, b: 10.0 }.freeze
+      # The dark mode text color.
+      DARK_FOREGROUND = { r: 245.0, g: 245.0, b: 244.0 }.freeze
 
       SANS_FALLBACKS = %w[ui-sans-serif system-ui sans-serif].freeze
       SERIF_FALLBACKS = %w[ui-serif Georgia serif].freeze
@@ -48,6 +54,7 @@ module Poetry
         ].join("\n")
       end
 
+      # The vanilla CSS token sheet for a domain: a :root block and a .dark block from the brand and styleguide.
       def derive_css_variables(domain, brand = nil, styleguide = nil)
         root_body, dark_body = bodies(brand, styleguide)
         [
@@ -57,6 +64,7 @@ module Poetry
         ].join("\n")
       end
 
+      # The light and dark token bodies: each palette's lines plus the fonts, radius, shadows, tracking and spacing.
       def bodies(brand, styleguide)
         light = build_palette(brand, styleguide, "light")
         dark = build_palette(brand, styleguide, "dark")
@@ -73,6 +81,7 @@ module Poetry
 
       # --- Color utilities -------------------------------------------------
 
+      # An RGB hash from a hex color in three, six or eight digits; nil for anything else.
       def parse_hex(hex)
         return nil unless hex
 
@@ -88,17 +97,20 @@ module Poetry
         end
       end
 
+      # An RGB hash as a six-digit hex color.
       def to_hex(color)
         hx = ->(n) { format("%02x", n.round.clamp(0, 255)) }
         "##{hx.call(color[:r])}#{hx.call(color[:g])}#{hx.call(color[:b])}"
       end
 
+      # The linear mix of two RGB colors by an amount from zero to one.
       def mix(from, to, amount)
         { r: from[:r] + ((to[:r] - from[:r]) * amount),
           g: from[:g] + ((to[:g] - from[:g]) * amount),
           b: from[:b] + ((to[:b] - from[:b]) * amount) }
       end
 
+      # The relative luminance of an RGB color, per the WCAG formula.
       def luminance(color)
         f = lambda do |c|
           s = c / 255.0
@@ -107,10 +119,13 @@ module Poetry
         (0.2126 * f.call(color[:r])) + (0.7152 * f.call(color[:g])) + (0.0722 * f.call(color[:b]))
       end
 
+      # Whether a color is dark enough to want a light foreground.
       def dark?(color) = luminance(color) < 0.5
 
+      # The foreground that reads on a background: white on dark, near-black on light.
       def readable(background) = dark?(background) ? "#ffffff" : "#0a0a0a"
 
+      # A number held between min and max.
       def clamp(number, min, max) = number.clamp(min, max)
 
       # JS parseFloat: leading number or nil - "5.9%" => 5.9, "abc" => nil.
@@ -132,6 +147,7 @@ module Poetry
         js_to_fixed(number, decimals).sub(/\.?0+\z/, "")
       end
 
+      # An RGB hash as an hsl() token with one decimal on each channel.
       def rgb_to_hsl_token(color)
         rr = color[:r] / 255.0
         gg = color[:g] / 255.0
@@ -156,6 +172,7 @@ module Poetry
         "hsl(#{format_number(h, 1)} #{format_number(s * 100, 1)}% #{format_number(l * 100, 1)}%)"
       end
 
+      # A CSS color as an hsl() token: hex directly, hsl and rgb functions through their parsers; nil otherwise.
       def normalize_css_color(raw)
         return nil unless raw
 
@@ -166,6 +183,7 @@ module Poetry
         normalize_hsl(value) || normalize_rgb(value)
       end
 
+      # An hsl() or hsla() string as an hsl() token with its alpha, or nil when it does not parse.
       def normalize_hsl(value)
         m = value.match(/\Ahsla?\((.+)\)\z/i)
         return nil unless m
@@ -182,6 +200,7 @@ module Poetry
           opacity: alpha && clamp(alpha, 0, 1) }.compact
       end
 
+      # An rgb() or rgba() string as an hsl() token with its alpha, or nil when it does not parse.
       def normalize_rgb(value)
         m = value.match(/\Argba?\((.+)\)\z/i)
         return nil unless m
@@ -199,12 +218,14 @@ module Poetry
           opacity: alpha && clamp(alpha, 0, 1) }.compact
       end
 
+      # A color function's body split into its channels and the slash alpha, when one is written.
       def split_channels(body)
         body.include?("/") ? body.split("/", 2) : [body, nil]
       end
 
       # --- Length utilities ------------------------------------------------
 
+      # A length in pixels from a px, rem or em value; nil when it is not a length.
       def to_px(value)
         return nil unless value
 
@@ -216,18 +237,21 @@ module Poetry
         %w[rem em].include?(unit) ? n * 16 : n
       end
 
+      # The positive pixel lengths in a space-separated value.
       def to_px_list(value)
         return [] unless value
 
         value.to_s.strip.split(/\s+/).filter_map { |part| to_px(part) }.select(&:positive?)
       end
 
+      # A pixel length as a rem string with trailing zeros trimmed.
       def px_to_rem(pixels)
         "#{js_to_fixed(pixels / 16.0, 4).sub(/\.?0+\z/, "")}rem"
       end
 
       # --- Font utilities --------------------------------------------------
 
+      # A font family name quoted when it carries characters a bare CSS identifier cannot.
       def quote_if_needed(name)
         trimmed = name.strip.gsub(/\A["']|["']\z/, "")
         return trimmed if trimmed.empty?
@@ -236,6 +260,7 @@ module Poetry
         trimmed
       end
 
+      # A font stack from the primary family, its fallbacks and the generic family, deduplicated case-insensitively.
       def build_font_stack(primary, fallbacks, generic)
         seen = {}
         stack = []
@@ -255,6 +280,7 @@ module Poetry
         stack.join(", ")
       end
 
+      # A font family's class, sans, serif, mono or unknown, from the font links or the family name.
       def classify_family(family, font_links)
         return "unknown" unless family
 
@@ -274,6 +300,7 @@ module Poetry
         "unknown"
       end
 
+      # The first font link whose category reads as monospace, or nil.
       def find_mono_family(font_links)
         font_links&.each do |name, link|
           return name if link["category"]&.downcase&.include?("mono")
@@ -281,6 +308,7 @@ module Poetry
         nil
       end
 
+      # The first font link whose category reads as serif, skipping the excluded names, or nil.
       def find_serif_family(font_links, exclude)
         font_links&.each do |name, link|
           next if exclude.include?(name.downcase)
@@ -291,6 +319,7 @@ module Poetry
         nil
       end
 
+      # The sans, serif and mono stacks for a styleguide, from its body and heading fonts and its font links.
       def pick_fonts(styleguide)
         body = styleguide&.dig("typography", "p")
         h1 = styleguide&.dig("typography", "headings", "h1")
@@ -324,6 +353,7 @@ module Poetry
 
       # --- Radius / shadows / spacing --------------------------------------
 
+      # The radius token from a styleguide's card or button, clamped between two and sixteen pixels.
       def pick_radius(styleguide)
         card_radius = to_px(styleguide&.dig("components", "card", "borderRadius"))
         button_radius = to_px(styleguide&.dig("components", "button", "primary", "borderRadius"))
@@ -333,11 +363,13 @@ module Poetry
         px_to_rem(px.clamp(2, 16))
       end
 
+      # A length as a px token, or the fallback when it is not a length.
       def normalize_px_token(value, fallback)
         px = to_px(value)
         px.nil? ? fallback : "#{format_number(px, 2)}px"
       end
 
+      # A box-shadow value split into its comma-separated layers, commas inside functions kept.
       def split_shadow_layers(value)
         layers = []
         depth = 0
@@ -354,10 +386,12 @@ module Poetry
         layers.reject(&:empty?)
       end
 
+      # The color function or hex color inside one shadow layer, or nil.
       def find_color_snippet(layer)
         layer[/\b(?:rgba?|hsla?)\([^)]+\)/i] || layer[/#[0-9a-f]{3,8}\b/i]
       end
 
+      # The first layer of a box-shadow value as offsets, blur, spread, color and opacity; nil when unusable.
       def parse_box_shadow(value)
         return nil if !value || value.strip.downcase == "none"
 
@@ -379,6 +413,7 @@ module Poetry
           opacity: color && color[:opacity] }
       end
 
+      # An hsl() or rgb() token with the opacity written as its alpha.
       def color_with_opacity(color, opacity)
         alpha = format_number(clamp(opacity, 0, 1), 4)
         if (m = color.match(/\Ahsl\((.+)\)\z/i))
@@ -390,6 +425,7 @@ module Poetry
         end
       end
 
+      # The shadow color when the styleguide gives none: a foreground tint on light, near-black on dark.
       def fallback_shadow_color(palette, mode)
         bg = parse_hex(palette[:background])
         fg = parse_hex(palette[:foreground])
@@ -399,6 +435,7 @@ module Poetry
         fg ? rgb_to_hsl_token(fg) : "hsl(0 0% 5%)"
       end
 
+      # The shadow token set from one base shadow: the base parts and the size ramp at quiet, main and loud opacities.
       def build_shadow_tokens(base)
         half = base[:opacity] * 0.5
         heavy = [base[:opacity] * 2.5, 0.75].min
@@ -420,6 +457,7 @@ module Poetry
           shadow2xl: "#{first} #{loud}" }
       end
 
+      # The shadow tokens for a styleguide and palette, from the first parsable shadow among its candidates.
       def pick_shadows(styleguide, palette, mode)
         s = styleguide&.dig("shadows")
         candidates = [
@@ -440,6 +478,7 @@ module Poetry
         )
       end
 
+      # The median of a list of numbers, nil for an empty one.
       def median(values)
         return nil if values.empty?
 
@@ -450,6 +489,7 @@ module Poetry
         (sorted[mid - 1] + sorted[mid]) / 2.0
       end
 
+      # The spacing base unit implied by a styleguide's element spacing, or nil when none reads.
       def pick_spacing(styleguide)
         sp = styleguide&.dig("elementSpacing")
         divided = lambda do |value, divisor|
@@ -474,6 +514,7 @@ module Poetry
         px_to_rem(safe_unit)
       end
 
+      # The normal letter spacing as an em token, from the body or heading tracking.
       def pick_tracking_normal(styleguide)
         values = [styleguide&.dig("typography", "p", "letterSpacing"),
                   styleguide&.dig("typography", "headings", "h1", "letterSpacing")]
@@ -491,120 +532,134 @@ module Poetry
 
       # --- Palette ---------------------------------------------------------
 
+      # The semantic palette for one mode from the brand colors and the
+      # styleguide: the source colors read once, the roles taken directly
+      # when the styleguide describes this mode and derived when it
+      # describes the other, then the palette written out as hex.
       def build_palette(brand, styleguide, mode)
-        sg_mode = styleguide&.dig("mode")
-        source_is_light = sg_mode != "dark"
+        sources = palette_sources(brand, styleguide)
+        source_is_light = styleguide&.dig("mode") != "dark"
         direct = mode == (source_is_light ? "light" : "dark")
+        roles = direct ? direct_roles(sources, mode) : derived_roles(sources, mode)
+        palette_hash(roles, mode, chart_series(roles, sources[:brand_colors]))
+      end
 
-        brand_colors = (brand&.dig("colors") || []).filter_map { |c| parse_hex(c["hex"]) }
-        named_brand_accent = parse_hex(
-          (brand&.dig("colors") || []).find do |c|
-            /accent|secondary|highlight|support/i.match?(c["name"] || "")
-          end&.dig("hex")
-        )
-
-        sg_bg = parse_hex(styleguide&.dig("colors", "background"))
-        sg_fg = parse_hex(styleguide&.dig("colors", "text"))
-        sg_accent = parse_hex(styleguide&.dig("colors", "accent"))
-
-        btn_primary = styleguide&.dig("components", "button", "primary")
-        btn_secondary = styleguide&.dig("components", "button", "secondary")
-        btn_link = styleguide&.dig("components", "button", "link")
+      # The colors the brand and the styleguide supply, parsed, with the
+      # source accent resolved: the styleguide's, else the link button's,
+      # else a brand color named as one, else the second brand color.
+      def palette_sources(brand, styleguide)
+        colors = brand&.dig("colors") || []
+        button = ->(kind, key) { parse_hex(styleguide&.dig("components", "button", kind, key)) }
         card = styleguide&.dig("components", "card")
-
-        sg_primary_bg = parse_hex(btn_primary&.dig("backgroundColor"))
-        sg_primary_fg = parse_hex(btn_primary&.dig("color"))
-        sg_secondary_bg = parse_hex(btn_secondary&.dig("backgroundColor"))
-        sg_secondary_fg = parse_hex(btn_secondary&.dig("color"))
-        sg_link_accent = parse_hex(btn_link&.dig("backgroundColor") || btn_link&.dig("color"))
-        sg_card_bg = parse_hex(card&.dig("backgroundColor"))
-        sg_card_fg = parse_hex(card&.dig("textColor"))
-        sg_card_border = parse_hex(card&.dig("borderColor"))
-        sg_btn_border = parse_hex(btn_secondary&.dig("borderColor") || btn_primary&.dig("borderColor"))
-        source_accent = sg_accent || sg_link_accent || named_brand_accent || brand_colors[1]
-
-        if direct
-          background = sg_bg || (mode == "light" ? WHITE : { r: 23.0, g: 23.0, b: 21.0 })
-          foreground = sg_fg || (mode == "light" ? { r: 10.0, g: 10.0, b: 10.0 } : { r: 245.0, g: 245.0, b: 244.0 })
-          primary = sg_primary_bg || brand_colors[0] || source_accent || foreground
-          primary_foreground = sg_primary_bg ? sg_primary_fg : nil
-          accent = source_accent || primary
-          secondary = sg_secondary_bg ||
-                      (source_accent ? mix(background, source_accent, 0.16) : nil) ||
-                      mix(background, primary, 0.18)
-          secondary_foreground = sg_secondary_bg ? sg_secondary_fg : nil
-          card_bg = sg_card_bg || mix(background, foreground, 0.03)
-          card_fg = sg_card_fg
-          border = sg_card_border || sg_btn_border
-        else
-          if mode == "light"
-            background = WHITE
-            foreground = { r: 10.0, g: 10.0, b: 10.0 }
-          else
-            background = { r: 23.0, g: 23.0, b: 21.0 }
-            foreground = { r: 245.0, g: 245.0, b: 244.0 }
-          end
-          base_primary = sg_primary_bg || brand_colors[0] || source_accent || foreground
-          primary = if mode == "dark" && dark?(base_primary) then mix(base_primary, WHITE, 0.3)
-                    elsif mode == "light" && !dark?(base_primary) then mix(base_primary, BLACK, 0.15)
-                    else base_primary
-                    end
-          primary_foreground = sg_primary_bg ? sg_primary_fg : nil
-          base_accent = source_accent || primary
-          accent = if mode == "dark" && dark?(base_accent) then mix(base_accent, WHITE, 0.25)
-                   elsif mode == "light" && !dark?(base_accent) then mix(base_accent, BLACK, 0.12)
-                   else base_accent
-                   end
-          secondary = sg_secondary_bg || mix(background, accent, mode == "light" ? 0.16 : 0.24)
-          secondary_foreground = sg_secondary_bg ? sg_secondary_fg : nil
-          card_bg = mix(background, foreground, mode == "light" ? 0.03 : 0.07)
-          card_fg = nil
-          border = nil
+        named = colors.find { |c| /accent|secondary|highlight|support/i.match?(c["name"] || "") }
+        brand_colors = colors.filter_map { |c| parse_hex(c["hex"]) }
+        { brand_colors: brand_colors,
+          bg: parse_hex(styleguide&.dig("colors", "background")), fg: parse_hex(styleguide&.dig("colors", "text")),
+          primary_bg: button.call("primary", "backgroundColor"), primary_fg: button.call("primary", "color"),
+          secondary_bg: button.call("secondary", "backgroundColor"), secondary_fg: button.call("secondary", "color"),
+          card_bg: parse_hex(card&.dig("backgroundColor")), card_fg: parse_hex(card&.dig("textColor")),
+          card_border: parse_hex(card&.dig("borderColor")),
+          button_border: button.call("secondary", "borderColor") || button.call("primary", "borderColor"),
+          accent: parse_hex(styleguide&.dig("colors", "accent")) ||
+            button.call("link", "backgroundColor") || button.call("link", "color") ||
+            parse_hex(named&.dig("hex")) || brand_colors[1] }
+      end
+
+      # The mode's default canvas.
+      def mode_background(mode) = mode == "light" ? WHITE : DARK_BACKGROUND
+
+      # The mode's default text color.
+      def mode_foreground(mode) = mode == "light" ? LIGHT_FOREGROUND : DARK_FOREGROUND
+
+      # The roles when the styleguide describes this very mode: what it
+      # says, the gaps filled from the brand and by mixing.
+      def direct_roles(sources, mode)
+        background = sources[:bg] || mode_background(mode)
+        foreground = sources[:fg] || mode_foreground(mode)
+        primary = sources[:primary_bg] || sources[:brand_colors][0] || sources[:accent] || foreground
+        secondary = sources[:secondary_bg] ||
+                    (sources[:accent] ? mix(background, sources[:accent], 0.16) : nil) ||
+                    mix(background, primary, 0.18)
+        { background: background, foreground: foreground, primary: primary,
+          primary_foreground: sources[:primary_bg] ? sources[:primary_fg] : nil,
+          accent: sources[:accent] || primary, secondary: secondary,
+          secondary_foreground: sources[:secondary_bg] ? sources[:secondary_fg] : nil,
+          card_bg: sources[:card_bg] || mix(background, foreground, 0.03), card_fg: sources[:card_fg],
+          border: sources[:card_border] || sources[:button_border] }
+      end
+
+      # The roles when the styleguide describes the other mode: this mode's
+      # own canvas, the primary and accent pulled toward it, the rest mixed.
+      def derived_roles(sources, mode)
+        background = mode_background(mode)
+        foreground = mode_foreground(mode)
+        base_primary = sources[:primary_bg] || sources[:brand_colors][0] || sources[:accent] || foreground
+        primary = toward_mode(base_primary, mode, 0.3, 0.15)
+        accent = toward_mode(sources[:accent] || primary, mode, 0.25, 0.12)
+        { background: background, foreground: foreground, primary: primary,
+          primary_foreground: sources[:primary_bg] ? sources[:primary_fg] : nil,
+          accent: accent,
+          secondary: sources[:secondary_bg] || mix(background, accent, mode == "light" ? 0.16 : 0.24),
+          secondary_foreground: sources[:secondary_bg] ? sources[:secondary_fg] : nil,
+          card_bg: mix(background, foreground, mode == "light" ? 0.03 : 0.07), card_fg: nil, border: nil }
+      end
+
+      # A color pulled toward the mode's canvas when it would sink into it:
+      # lightened on a dark mode when it is dark, darkened on a light mode
+      # when it is light, else as it is.
+      def toward_mode(color, mode, dark_share, light_share)
+        if mode == "dark" && dark?(color) then mix(color, WHITE, dark_share)
+        elsif mode == "light" && !dark?(color) then mix(color, BLACK, light_share)
+        else color
         end
+      end
 
-        muted = mix(background, foreground, mode == "light" ? 0.05 : 0.1)
-        muted_fg = mix(foreground, background, 0.4)
-        final_border = border || mix(background, foreground, mode == "light" ? 0.12 : 0.2)
-        sidebar = mix(background, foreground, mode == "light" ? 0.04 : 0.05)
-
-        chart_candidates = [accent, primary, secondary] + brand_colors
+      # Five chart colors: the accent, primary, secondary and brand colors
+      # without repeats, padded with tints and shades of the primary.
+      def chart_series(roles, brand_colors)
         seen = {}
-        unique_chart = chart_candidates.select do |color|
+        unique = ([roles[:accent], roles[:primary], roles[:secondary]] + brand_colors).select do |color|
           hex = to_hex(color)
           next false if seen[hex]
 
           seen[hex] = true
         end
-        chart = [
-          unique_chart[0] || primary,
-          unique_chart[1] || mix(primary, WHITE, 0.3),
-          unique_chart[2] || mix(primary, BLACK, 0.25),
-          unique_chart[3] || mix(primary, WHITE, 0.55),
-          unique_chart[4] || mix(primary, BLACK, 0.45)
-        ]
-
+        primary = roles[:primary]
+        [unique[0] || primary, unique[1] || mix(primary, WHITE, 0.3), unique[2] || mix(primary, BLACK, 0.25),
+         unique[3] || mix(primary, WHITE, 0.55), unique[4] || mix(primary, BLACK, 0.45)]
+      end
+
+      # The palette as hex: the roles, the muted, border and sidebar tones
+      # mixed from the canvas, and the readable foregrounds.
+      def palette_hash(roles, mode, chart)
+        background, foreground, primary, accent, secondary =
+          roles.values_at(:background, :foreground, :primary, :accent, :secondary)
+        light = mode == "light"
+        border = roles[:border] || mix(background, foreground, light ? 0.12 : 0.2)
+        card_fg = roles[:card_fg] || foreground
+        primary_fg = roles[:primary_foreground] ? to_hex(roles[:primary_foreground]) : readable(primary)
+        secondary_fg = roles[:secondary_foreground] ? to_hex(roles[:secondary_foreground]) : readable(secondary)
         { background: to_hex(background), foreground: to_hex(foreground),
-          card: to_hex(card_bg), card_foreground: to_hex(card_fg || foreground),
-          popover: to_hex(card_bg), popover_foreground: to_hex(card_fg || foreground),
-          primary: to_hex(primary),
-          primary_foreground: primary_foreground ? to_hex(primary_foreground) : readable(primary),
+          card: to_hex(roles[:card_bg]), card_foreground: to_hex(card_fg),
+          popover: to_hex(roles[:card_bg]), popover_foreground: to_hex(card_fg),
+          primary: to_hex(primary), primary_foreground: primary_fg,
           secondary: to_hex(secondary),
-          secondary_foreground: secondary_foreground ? to_hex(secondary_foreground) : readable(secondary),
-          muted: to_hex(muted), muted_foreground: to_hex(muted_fg),
+          secondary_foreground: secondary_fg,
+          muted: to_hex(mix(background, foreground, light ? 0.05 : 0.1)),
+          muted_foreground: to_hex(mix(foreground, background, 0.4)),
           accent: to_hex(accent), accent_foreground: readable(accent),
-          destructive: mode == "light" ? "#dc2626" : "#ef4444",
-          destructive_foreground: "#ffffff",
-          border: to_hex(final_border), input: to_hex(final_border), ring: to_hex(accent),
+          destructive: light ? "#dc2626" : "#ef4444", destructive_foreground: "#ffffff",
+          border: to_hex(border), input: to_hex(border), ring: to_hex(accent),
           chart: chart.map { |color| to_hex(color) },
-          sidebar: to_hex(sidebar), sidebar_foreground: to_hex(foreground),
-          sidebar_primary: to_hex(primary),
-          sidebar_primary_foreground: primary_foreground ? to_hex(primary_foreground) : readable(primary),
+          sidebar: to_hex(mix(background, foreground, light ? 0.04 : 0.05)), sidebar_foreground: to_hex(foreground),
+          sidebar_primary: to_hex(primary), sidebar_primary_foreground: primary_fg,
           sidebar_accent: to_hex(accent), sidebar_accent_foreground: readable(accent),
-          sidebar_border: to_hex(final_border), sidebar_ring: to_hex(accent) }
+          sidebar_border: to_hex(border), sidebar_ring: to_hex(accent) }
       end
 
       # --- Output formatting -----------------------------------------------
 
+      # A palette as CSS custom property declarations.
       def palette_lines(palette)
         ["--background: #{palette[:background]};", "--foreground: #{palette[:foreground]};",
          "--card: #{palette[:card]};", "--card-foreground: #{palette[:card_foreground]};",
@@ -625,6 +680,7 @@ module Poetry
          "--sidebar-border: #{palette[:sidebar_border]};", "--sidebar-ring: #{palette[:sidebar_ring]};"]
       end
 
+      # The font, radius, shadow, tracking and spacing declarations.
       def non_color_lines(fonts, radius, shadows, tracking_normal = nil, spacing = nil)
         lines = ["--font-sans: #{fonts[:sans]};", "--font-serif: #{fonts[:serif]};",
                  "--font-mono: #{fonts[:mono]};", "--radius: #{radius};",
@@ -640,10 +696,12 @@ module Poetry
         lines
       end
 
+      # The lines indented by two spaces and joined.
       def indent(lines)
         lines.map { |line| "  #{line}" }.join("\n")
       end
 
+      # The inline theme block mapping the color, font and radius tokens onto the framework's names.
       def theme_inline_block
         pairs = %w[background foreground card card-foreground popover popover-foreground
                    primary primary-foreground secondary secondary-foreground muted
@@ -663,6 +721,7 @@ module Poetry
         "@theme inline {\n#{indent(lines)}\n}"
       end
 
+      # The base layer applying the border, outline, background and foreground defaults.
       def layer_base
         <<~CSS.strip
           @layer base {
@@ -675,6 +734,17 @@ module Poetry
           }
         CSS
       end
+
+      private_class_method :bodies, :parse_hex, :to_hex, :mix, :readable, :js_float, :js_to_fixed, :format_number
+      private_class_method :rgb_to_hsl_token, :normalize_css_color, :normalize_hsl, :normalize_rgb, :split_channels
+      private_class_method :to_px, :to_px_list, :px_to_rem, :quote_if_needed, :build_font_stack, :classify_family
+      private_class_method :find_mono_family, :find_serif_family, :pick_fonts, :pick_radius, :normalize_px_token
+      private_class_method :split_shadow_layers, :find_color_snippet, :parse_box_shadow, :color_with_opacity
+      private_class_method :fallback_shadow_color, :build_shadow_tokens, :pick_shadows, :pick_spacing
+      private_class_method :pick_tracking_normal, :build_palette, :palette_lines, :non_color_lines
+      private_class_method :palette_sources, :mode_background, :mode_foreground, :direct_roles, :derived_roles
+      private_class_method :toward_mode, :chart_series, :palette_hash
+      private_class_method :theme_inline_block, :layer_base
     end
   end
 end

data/lib/poetry/extract/fetch.rb

@@ -49,7 +49,6 @@ module Poetry
       end
 
       # The no-client Signals shape: homepage markdown, nothing else.
-      # @api private
       def degraded(domain, homepage_fetcher)
         Signals.new(styleguide: nil, brand: nil, screenshot_url: nil,
                     markdown: homepage_fetcher.call(domain).to_s)
@@ -66,7 +65,6 @@ module Poetry
 
       # SDK responses expose the payload as an accessor; plain-hash fakes
       # (tests, cassettes) work identically.
-      # @api private
       def value_of(response, key)
         return response[key.to_s] || response[key] if response.is_a?(Hash)
 
@@ -97,6 +95,8 @@ module Poetry
       rescue StandardError
         ""
       end
+
+      private_class_method :degraded, :value_of
     end
   end
 end

data/lib/poetry/extract/runner.rb

@@ -53,6 +53,7 @@ module Poetry
 
       # Reduce a URL or bare domain to its lowercase host.
       #
+      # @param domain [String] a URL or a bare host
       # @return [String]
       def normalize_domain(domain)
         domain.to_s.strip.downcase
@@ -62,6 +63,9 @@ module Poetry
       # The composed document must at least parse as DESIGN.md; a missing
       # frontmatter is a warning, not a failure - prose-only documents
       # still carry the body sections, and import will say so again.
+      #
+      # @param design_md [String] the composed DESIGN.md document
+      # @param io [IO] where warnings are printed
       def validate!(design_md, io)
         parsed = Poetry::Core::DesignMd.parse(design_md)
         io.puts "note: composed DESIGN.md has no frontmatter tokens" unless parsed.is_a?(Hash) && parsed.any?

data/lib/poetry/extract/version.rb

@@ -3,6 +3,6 @@
 module Poetry
   module Extract
     # The gem version.
-    VERSION = "0.1.3"
+    VERSION = "0.1.5"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poetry-extract
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Matt Solt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.1.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.1.5
 - !ruby/object:Gem::Dependency
   name: context.dev
   requirement: !ruby/object:Gem::Requirement
@@ -47,6 +47,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".mcp.json"
+- ".yard-lint.yml"
+- ".yard_coverage_all"
+- Archspec.rb
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -83,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Domain in, theme out: extract a DESIGN.md + design tokens from any public
   website.'