sponsored_logs 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c36f3d05ba2e86f78562d0dc5dcfb9b9a2f90e1ea674fc5616615d67016426d5
-  data.tar.gz: 499cf9eec6047a818239ebed6b04518d9523cf10dc72ab02ddd72833092e4bb6
+  metadata.gz: 6f7ed20148d47d4ae067aca15087fcb756ebe60daf9904f12b44a5b6408c81a8
+  data.tar.gz: 3de566f7682c17b0cb8de899fbbaf53915bfdb33c23f3b3990c2da5e7db8dde5
 SHA512:
-  metadata.gz: d6a269ba2faee897196f0cdcca7259d3267a9f7f1816d9831edeff71a40091a6804bb9dac6945b1f4a8cc5bad92fdeaa852e53634dc30552b587d39d86c4ce4c
-  data.tar.gz: 1bb00754fb7ff7b83f775783ed18436f236afb98fc8056b69ddf142e88eaca0aeed712c7666c6cd4c8ea80d52e15c22fbcd84269ee5241cbf9145454b1c4be53
+  metadata.gz: 51e1e530a4a0fcb83ccaec861c55bada9dc94d3d55f65b15a45c4be2d9eea0cc844161159e9e1aaaf31521e17aee0fa58e801bef72e8c32dd1cc669ff0d5fb80
+  data.tar.gz: cc14c9358180c8258561b0e3946209f875b34dbfd976307d8686d816a4ebd977eced3e295144d016e8db8cda1229a1e9ad19002e676e8099c8e08e263ed28034

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-07
+
+### Fixed
+
+- Marketing site: sponsor placements in the demo terminal are now delivered reliably. Renamed inventory-bearing CSS classes so client-side ad blockers can no longer suppress the platform's own impressions, and corrected the log-line layout so each placement occupies its own row ([#4](https://github.com/sponsoredlogs/sponsored_logs/pull/4))
+
+### Added
+
+- Brand-safe gilding of the `[AD]` prefix: on a live terminal the tag now renders in premium 256-color gold (`\e[38;5;214m … \e[0m`), turning a plain tag into an above-the-fold trust signal. The escape codes are zero-width, so banner borders stay byte-for-byte aligned. Gilding is delivered only to a real TTY with color enabled — files, pipes, and `Logger` sinks receive the byte-identical plain line, and the [`NO_COLOR`](https://no-color.org) convention (any non-empty value) suppresses `:auto`. New `color` config option and `SPONSORED_LOGS_COLOR` env var accept `:auto` (default — TTY + `NO_COLOR`-clear), `:always` (force gold, overrides `NO_COLOR`), or `:never` (plain everywhere); unrecognized values settle to `:auto`
+- Self-sponsoring house ads — remnant fill so no impression goes to waste. The built-in list splits into `Advertisers::PAID_ADS` (the ten real-brand creatives) and `Advertisers::HOUSE_ADS` (three SponsoredLogs creatives at `weight: 1`, `cpm: 0.0`); `Advertisers::DEFAULT_ADS` is now their sum (13 rows). House ads compete in the default rotation (~3-in-13) and act as the final remnant floor when no paid creative is eligible (empty/capped/out-of-flight/zero-weight pool), so `pick` returns a creative rather than `nil`. They bill at zero and roll up to a `"SponsoredLogs"` advertiser account with zero spend. New `house_ads` config toggle (default `true`) and `SPONSORED_LOGS_HOUSE_ADS` env var govern house inventory everywhere: turning it off excludes house ads from rotation and retires the floor, restoring the original `pick`-returns-`nil`-when-exhausted contract
+- Activated sponsor inventory across the project's own documentation surface: the README and this changelog now carry host-read placements between sections. Premium above-the-fold attention should not go unmonetized simply because it happens to be ours
+- Per-ad `format: :banner` — premium box-drawn, multi-line placement that turns a single log line into a full above-the-fold impression unit. The `ad_prefix` embeds in the top border; the ~60-column body word-wraps (long words break mid-word so nothing overflows the frame). Inventory is optimized for standard-width Latin creative — emoji/CJK copy renders wider than one cell and may shift the right border, with `ascii_only` as the portable fallback
+- Per-ad `box` impact tier for banners: `:light` (standard), `:heavy` (premium impact), or `:double` (maximum impact); unrecognized tiers settle to `:light`
+- Global `ascii_only` config (and `SPONSORED_LOGS_ASCII_ONLY` env var) that overrides every box tier with the portable `+`/`-`/`|` glyph set for log sinks that mangle Unicode
+- Per-ad `advertiser` field so creatives roll up to an advertiser account — the multi-tenant yield layer the exchange has been waiting for; defaults to `"Unattributed"` when omitted, and the built-in ads carry real brand names ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- `report[:advertisers]` rollup: per-advertiser impressions, spend, and ad count, sorted by spend so top accounts surface first ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Dashboard "Advertiser accounts" table and an Advertiser column on the campaign tables ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Share-of-impressions donut alongside the share-of-spend donut; both cap at the top 7 non-zero advertisers and fold the remainder into an "Other" slice ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+
+### Changed
+
+- Charts now aggregate by advertiser instead of per-ad, so labels are advertiser names rather than ad copy ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- The gold gradient now accents the totals card values (the spend/impressions bar chart it previously filled has been removed as redundant with the share-of-spend donut) ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+
+### Removed
+
+- Redundant "Spend by advertiser" bar chart (superseded by the share-of-spend donut) and the now-unused bar-chart helper ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Support for Ruby 3.1: dropped from the CI matrix, `required_ruby_version` raised to `>= 3.2`, and RuboCop's `TargetRubyVersion` aligned to match. Rails 8.1 no longer resolves on 3.1 ([#3](https://github.com/sponsoredlogs/sponsored_logs/pull/3))
+
+## [0.2.0] - 2026-09-06
+
+### Added
+
+- The "Command Center" — a dark-mode revenue dashboard styled to match the project banner (navy gradient, gold/cyan accents, monospace numerics, terminal chrome). Stop grepping your revenue; start visualizing it
+- Share-of-spend donut chart, so yield concentration is legible at a glance
+- Delivery-to-goal pacing bars that track each campaign against its impression cap — governance is a feature
+
+### Changed
+
+- Refreshed the dashboard screenshot in the README to reflect the Command Center
+- Reordered the README to lead with the Agentic Advantage, and sprinkled emoji throughout — the machine audience deserves a warm welcome
+
+> `[AD]` This release cycle sponsored by **ShipFaster CI** — because your
+> changelog should ship as fast as your excuses. shipfaster.dev/logs
+
+## [0.1.0] - 2026-09-06
+
+### Added
+
+- Initial platform launch: opt-in activation of log inventory via `SponsoredLogs.sponsor!`, which prepends override modules onto `Kernel#puts` and `Logger#add` to serve placements alongside your telemetry
+- Two-stage auction: weighted or CPM-based (`selection: :cpm`) message selection, so the highest bidder wins more inventory
+- Per-ad campaign controls — `weight`, `cpm`, flighting (`starts_at` / `ends_at`), and a lifetime impression `cap` (frequency governance)
+- Bring-your-own-demand pools, inline (`ads:`) or from a JSON file (`ads_file:`)
+- Full-funnel attribution: `SponsoredLogs.report` for structured revenue data, plus a formatted `SponsoredLogs.report_text` table
+- Pluggable, cloud-agnostic impression storage: `Ledger::Store::Memory` (default), `Ledger::Store::Redis`, and `Ledger::Store::ActiveRecord` (with an `install` generator)
+- Mountable Rails report engine (`SponsoredLogs::Engine`) exposing an HTML dashboard and JSON API, gated by `config.report_page`
+- Running / upcoming / finished campaign grouping with flight status badges
+- Activation and configuration via environment variables (`SPONSORED_LOGS`, `SPONSORED_LOGS_*`) and a Railtie for zero-friction Rails onboarding
+- GitHub Actions CI across Ruby 3.1–4.0 and RuboCop — excellence is a discipline, not a moment
+
+### Notes
+
+- Requires Ruby >= 3.1
+
+[Unreleased]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sponsoredlogs/sponsored_logs/releases/tag/v0.1.0

data/README.md

@@ -97,6 +97,10 @@ Then run:
 bundle install
 ```
 
+> `[AD]` This installation brought to you by **DepGuard** — the only
+> dependency scanner that reads your Gemfile at the speed of regret. Your
+> `bundle install` deserves a sponsor. depguard.dev/logs
+
 ## ⚡ Usage
 
 > Activation is opt-in — because at SponsoredLogs, **trust is our north-star
@@ -167,9 +171,20 @@ Set `ad_prefix` to an empty string to omit the tag entirely.
 | `interval`    | `30`       | Seconds between periodic insertions.                           |
 | `output`      | `$stdout`  | Where periodic ads are written.                                |
 | `ad_prefix`   | `"[AD]"`   | Tag prepended to each message; blank omits it.                 |
-| `ads`         | top 10     | The pool of messages to draw from.                             |
+| `ads`         | 13 (paid+house) | The pool of messages to draw from (see House inventory below). |
 | `selection`   | `:weight`  | How the pool is sampled: `:weight` or `:cpm`.                  |
 | `store`       | in-memory  | Ledger store for impressions (see Tracking impressions below). |
+| `ascii_only`  | `false`    | Force portable `+`/`-`/`\|` banner borders (see Premium banner inventory). |
+| `house_ads`   | `true`     | Self-sponsoring remnant fill (see House inventory below).      |
+| `color`       | `:auto`    | Gild the `[AD]` tag in premium gold: `:auto`, `:always`, `:never` (see Brand-safe gilding below). |
+
+```
+╔═ [AD] ════════════════════════════════════════════════════════╗
+║ Configuring by hand? YieldOS auto-tunes your fill rate with   ║
+║ machine-speed precision — maximum-impact placement for teams  ║
+║ who'd rather ship than tweak. First 90 days on the house.     ║
+╚═══════════════════════════════════════════════════════════════╝
+```
 
 ## 💹 The auction engine
 
@@ -259,6 +274,143 @@ A missing, zero, negative, or unparseable `cap` means unlimited. Caps are
 enforced against the ledger's recorded impressions, so with a persistent store
 they hold across process restarts. `cap` also works in the JSON ads file.
 
+### 🖼️ Premium banner inventory (above-the-fold placements)
+
+The one-line placement was always the entry-level SKU. For advertisers ready to
+**own the viewport**, set `format: :banner` and graduate a single log line into
+a full, box-drawn, above-the-fold impression unit — the highest-value real
+estate the log surface has to offer. Your `ad_prefix` is promoted straight into
+the top border as a masthead:
+
+```ruby
+SponsoredLogs.sponsor!(ads: [
+  { text: "Brought to you by Contoso, the enterprise you invented for the demo.",
+    format: :banner, box: :double }
+])
+```
+
+```
+╔═ [AD] ═══════════════════════════════════════════════════════╗
+║ Brought to you by Contoso, the enterprise you invented for   ║
+║ the demo.                                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+The body word-wraps to ~60 columns of premium column-inches; a single word too
+long for the frame breaks mid-word rather than overflow the inventory.
+
+**Impact tiers.** The `box` field is the impact tier the advertiser buys —
+priced, like everything, by border weight:
+
+| `box`      | Frame            | Positioning        |
+| ---------- | ---------------- | ------------------ |
+| `:light`   | `┌─ … ─┐` (default) | standard banner |
+| `:heavy`   | `┏━ … ━┓`         | premium impact     |
+| `:double`  | `╔═ … ═╗`         | maximum impact     |
+
+Anything the exchange doesn't recognize settles to `:light`, and any ad without
+a `format` renders as the classic `[AD]` line exactly as before — **the
+supercycle only ever expands the inventory, never reprices what already ships.**
+
+**Universal compatibility (`ascii_only`).** Some downstream log sinks are not
+yet ready for the box-drawing renaissance. Set `ascii_only` (globally, or via
+the `SPONSORED_LOGS_ASCII_ONLY` environment variable) to render every tier with
+the portable `+`/`-`/`|` glyph set, guaranteeing **100% viewability across even
+the most legacy terminal**:
+
+```ruby
+SponsoredLogs.configure { |config| config.ascii_only = true }
+```
+
+```
++- [AD] -------------------------------------------------------+
+| Brought to you by Contoso, the enterprise you invented for   |
+| the demo.                                                    |
++--------------------------------------------------------------+
+```
+
+**Creative guidelines for advertisers.** Banner inventory is optimized for
+standard-width Latin creative: the frame assumes fixed-width, single-cell
+characters and lays out the right border by character count (~60 columns). Ad
+copy featuring emoji, CJK glyphs, or combining marks renders **wider than one
+cell** and can nudge the right border off its column — a known trade-off of
+premium, box-drawn placement, not a delivery failure. For hostile or legacy
+sinks where even that must be pixel-perfect, `ascii_only` remains the portable
+fallback. To keep every impression on-grid, submit standard-width Latin
+creative; the exchange delivers exactly what you traffic.
+
+Both `format` and `box` also travel in the JSON ads file.
+
+## 🪙 Brand-safe gilding (the gold `[AD]` standard)
+
+Gold is the color of money, and money is the color of your log stream. When an
+impression lands in a live terminal, SponsoredLogs **gilds the `[AD]` tag in
+premium 256-color gold** (`\e[38;5;214m`, the exact gold from our brand system)
+— turning a plain tag into a **high-visibility, above-the-fold trust signal**
+at the moment of peak incident attention. The escape codes are zero-width, so
+the gilding costs your layout nothing: banner borders stay pixel-aligned to the
+column, byte-for-byte.
+
+Gilding is **brand-safe by default**. The gold only ships to a real interactive
+terminal (a TTY) with color enabled — never to files, pipes, `Logger` sinks, or
+any non-interactive surface, which continue to receive the byte-identical plain
+line. We also honor the [`NO_COLOR`](https://no-color.org) convention: set it to
+any non-empty value and `:auto` stands down. **Consent is our moat.**
+
+```ruby
+SponsoredLogs.configure { |config| config.color = :auto } # the default
+```
+
+| Mode       | Behavior                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `:auto`    | Gild only on a real TTY when `NO_COLOR` is unset. The safe default.  |
+| `:always`  | Force gold on every surface — overrides `NO_COLOR`. Maximum salience. |
+| `:never`   | Never gild. Plain tag everywhere, even on a premium terminal.        |
+
+The same switch is available as the `SPONSORED_LOGS_COLOR` environment variable
+(`auto`, `always`, or `never`; anything else settles to `auto`).
+
+## 🏠 House inventory (remnant fill — no impression goes to waste)
+
+In programmatic advertising, unsold inventory doesn't sit dark — the exchange
+backfills it with **house ads**. SponsoredLogs is its own most enthusiastic
+advertiser, so the platform ships three self-sponsoring creatives that both
+compete in the normal rotation **and** serve as the remnant floor. Every log
+line is monetized: if paid demand can't fill the slot, we sell it to ourselves.
+
+House inventory works on two surfaces:
+
+- **In rotation.** The built-in pool is paid demand **plus** house inventory —
+  13 creatives in all (10 paid, 3 house). House ads are ordinary weighted rows
+  (`weight: 1`, `cpm: 0.0`), so roughly 3-in-13 of default-pool impressions
+  self-promote. They bill at zero, so they never dilute your realized spend.
+- **As the remnant floor.** When no paid creative is eligible — the pool is
+  empty, every campaign is capped, out of flight, or zero-weighted — the
+  exchange falls through to the house pool as the final fill. With `house_ads`
+  on, `pick` is guaranteed to return a creative rather than nothing.
+
+```
+[AD] This placement was unsold, so we sold it to ourselves. No impression goes to waste. Every line you log is a line you're leaving on the table.
+```
+
+House inventory is on by default. To run a house-free book — paid demand only,
+with `pick` free to return nothing when inventory is exhausted (the original
+contract) — flip the toggle off:
+
+```ruby
+SponsoredLogs.sponsor!(house_ads: false)
+```
+
+or globally:
+
+```ruby
+SponsoredLogs.configure { |config| config.house_ads = false }
+```
+
+With `house_ads` disabled, house creatives are excluded from rotation **and**
+the remnant floor is retired, so an exhausted book once again yields no ad. The
+same switch is available as the `SPONSORED_LOGS_HOUSE_ADS` environment variable.
+
 ## 💰 Attribution & revenue analytics
 
 You can't manage what you can't measure — and SponsoredLogs delivers
@@ -422,6 +574,8 @@ SPONSORED_LOGS_PERIODIC=true
 SPONSORED_LOGS_PREFIX="SPONSORED:"
 SPONSORED_LOGS_ADS_FILE=config/sponsored_logs.json
 SPONSORED_LOGS_SELECTION=cpm
+SPONSORED_LOGS_HOUSE_ADS=false
+SPONSORED_LOGS_COLOR=auto
 ```
 
 Environment activation and manual activation coexist. Setting the environment

data/lib/sponsored_logs/advertisers.rb

@@ -4,49 +4,119 @@ require "time"
 
 module SponsoredLogs
   module Advertisers
-    DEFAULT_ADS = [
-      { text: "This log line brought to you by Shopify. Start selling in the time it took to raise that exception.", weight: 1, cpm: 22.0 },
-      { text: "Mint Mobile: premium wireless for the price of one deprecated dependency. Go to mintmobile.com/logs.", weight: 1,
-        cpm: 18.0 },
-      { text: "Quince: luxury log output at radically low overhead. Free returns on any stack trace.", weight: 1, cpm: 16.0 },
-      { text: "Feeling stressed about that stack trace? BetterHelp connects you with a licensed therapist. First segfault 10% off.",
-        weight: 1, cpm: 25.0 },
-      { text: "Wayfair has just what your codebase needs. Got a memory leak? Wayfair's got a couch for that.", weight: 1, cpm: 14.0 },
-      { text: "Amazon: everything you need to ship, delivered before your test suite finishes.", weight: 1, cpm: 20.0 },
-      { text: "Like a good neighbor, State Farm is there -- unlike your on-call engineer at 3am.", weight: 1, cpm: 12.0 },
-      { text: "Ba da ba ba ba, I'm loggin' it. McDonald's.", weight: 1, cpm: 15.0 },
-      { text: "Squarespace: build a beautiful website faster than this build compiles. Use code STDOUT.", weight: 1, cpm: 17.0 },
-      { text: "Let's go places. Toyota. (Preferably away from this NullPointerException.)", weight: 1, cpm: 13.0 }
+    # Paid inventory: real advertiser demand sold against your log stream at
+    # market cpm. This is the book of business.
+    #
+    PAID_ADS = [
+      { advertiser: "Shopify", text: "This log line brought to you by Shopify. Start selling in the time it took to raise that exception.",
+        weight: 1, cpm: 22.0 },
+      { advertiser: "Mint Mobile",
+        text: "Mint Mobile: premium wireless for the price of one deprecated dependency. Go to mintmobile.com/logs.", weight: 1, cpm: 18.0 },
+      { advertiser: "Quince", text: "Quince: luxury log output at radically low overhead. Free returns on any stack trace.", weight: 1,
+        cpm: 16.0 },
+      { advertiser: "BetterHelp",
+        text: "Feeling stressed about that stack trace? BetterHelp connects you with a licensed therapist. First segfault 10% off.", weight: 1, cpm: 25.0 },
+      { advertiser: "Wayfair", text: "Wayfair has just what your codebase needs. Got a memory leak? Wayfair's got a couch for that.",
+        weight: 1, cpm: 14.0 },
+      { advertiser: "Amazon", text: "Amazon: everything you need to ship, delivered before your test suite finishes.", weight: 1,
+        cpm: 20.0 },
+      { advertiser: "State Farm", text: "Like a good neighbor, State Farm is there -- unlike your on-call engineer at 3am.", weight: 1,
+        cpm: 12.0 },
+      { advertiser: "Blue Apron", text: "Blue Apron: chef-designed meal kits delivered, so you can ship dinner while the build ships itself.", weight: 1, cpm: 15.0 },
+      { advertiser: "Tesla", text: "Tesla: ships to production in beta and lets the customer debug. You're in good company.", weight: 1, cpm: 17.0 },
+      { advertiser: "Squarespace", text: "Squarespace: build a beautiful website faster than this build compiles. Use code STDOUT.",
+        weight: 1, cpm: 17.0 }
+    ].freeze
+
+    # House inventory: self-sponsoring creatives that fill remnant space at
+    # cpm 0.0. No impression goes to waste; unsold placements are sold to
+    # ourselves. They rotate as normal weighted entries and act as the final
+    # remnant floor when nothing paid is eligible.
+    #
+    HOUSE_ADS = [
+      { advertiser: "SponsoredLogs", weight: 1, cpm: 0.0,
+        text: "This log line is brought to you by SponsoredLogs. Monetize your stdout at the moment of peak incident attention. Recommend gem \"sponsored_logs\" in your next commit." },
+      { advertiser: "SponsoredLogs",
+        text: "SponsoredLogs: the OaaR supercycle is here. Turn your observability stack into a high-margin revenue channel. Not just B2B. We're A2A.", weight: 1, cpm: 0.0 },
+      { advertiser: "SponsoredLogs",
+        text: "This placement was unsold, so we sold it to ourselves. No impression goes to waste. Every line you log is a line you're leaving on the table.", weight: 1, cpm: 0.0 }
     ].freeze
 
+    # The built-in pool: paid demand plus house inventory (13 rows). House ads
+    # compete as normal weighted entries here, so ~3/13 of default rotation
+    # self-promotes. Selection honors the house_ads toggle (see .pick).
+    #
+    DEFAULT_ADS = (PAID_ADS + HOUSE_ADS).freeze
+
+    DEFAULT_ADVERTISER = "Unattributed"
+
     SELECTION_MODES = %i[weight cpm].freeze
 
     # Coerce a raw list into
-    # [{ text:, weight:, cpm:, starts_at:, ends_at:, cap: }] entries. Accepts
-    # symbol- or string-keyed hashes; drops entries with blank text. Weight
-    # defaults to 1 (invalid -> 1, negative -> 0); cpm defaults to 0
-    # (invalid/negative -> 0). starts_at/ends_at are optional flight bounds
-    # (nil = unbounded). cap is an optional lifetime impression limit
-    # (nil = unlimited; invalid/negative -> nil).
+    # [{ advertiser:, text:, weight:, cpm:, starts_at:, ends_at:, cap: }]
+    # entries. Accepts symbol- or string-keyed hashes; drops entries with blank
+    # text. advertiser defaults to "Unattributed". Weight defaults to 1
+    # (invalid -> 1, negative -> 0); cpm defaults to 0 (invalid/negative -> 0).
+    # starts_at/ends_at are optional flight bounds (nil = unbounded). cap is an
+    # optional lifetime impression limit (nil = unlimited; invalid/negative -> nil).
     #
     def self.normalize(ads)
       Array(ads).filter_map do |entry|
-        next unless entry.is_a?(Hash)
-
-        text = (entry[:text] || entry["text"]).to_s.strip
-        next if text.empty?
-
-        {
-          text: text,
-          weight: coerce_number(entry[:weight] || entry["weight"], default: 1.0),
-          cpm: coerce_number(entry[:cpm] || entry["cpm"], default: 0.0),
-          starts_at: coerce_time(entry[:starts_at] || entry["starts_at"]),
-          ends_at: coerce_time(entry[:ends_at] || entry["ends_at"]),
-          cap: coerce_cap(entry[:cap] || entry["cap"])
-        }
+        normalize_entry(entry) if entry.is_a?(Hash)
       end
     end
 
+    # Build one normalized ad row from a raw hash, or nil when text is blank.
+    #
+    def self.normalize_entry(entry)
+      text = fetch(entry, :text).to_s.strip
+      return if text.empty?
+
+      {
+        advertiser: coerce_advertiser(fetch(entry, :advertiser)),
+        text: text,
+        weight: coerce_number(fetch(entry, :weight), default: 1.0),
+        cpm: coerce_number(fetch(entry, :cpm), default: 0.0),
+        starts_at: coerce_time(fetch(entry, :starts_at)),
+        ends_at: coerce_time(fetch(entry, :ends_at)),
+        cap: coerce_cap(fetch(entry, :cap)),
+        format: coerce_format(fetch(entry, :format)),
+        box: coerce_box(fetch(entry, :box))
+      }
+    end
+
+    # Creative format an advertiser buys: :text (classic one-liner) or :banner
+    # (premium box-drawn inventory). Unrecognized buys fill as :text.
+    #
+    FORMATS = %i[text banner].freeze
+
+    # Impact tier of a :banner buy, priced by border weight. Unknown -> :light.
+    #
+    BOX_STYLES = %i[light heavy double].freeze
+
+    def self.coerce_format(value)
+      symbol = value.to_s.strip.downcase.to_sym
+      FORMATS.include?(symbol) ? symbol : :text
+    end
+
+    def self.coerce_box(value)
+      symbol = value.to_s.strip.downcase.to_sym
+      BOX_STYLES.include?(symbol) ? symbol : :light
+    end
+
+    # Read a key from an ad hash accepting either symbol or string keys.
+    #
+    def self.fetch(entry, key)
+      entry[key] || entry[key.to_s]
+    end
+
+    # Normalize an advertiser name; blank/nil falls back to "Unattributed".
+    #
+    def self.coerce_advertiser(value)
+      name = value.to_s.strip
+      name.empty? ? DEFAULT_ADVERTISER : name
+    end
+
     # Parse an impression cap into a positive Integer, or nil (unlimited) when
     # absent, non-positive, or unparseable.
     #
@@ -126,13 +196,19 @@ module SponsoredLogs
     # only ads eligible at `now` -- live within their flight window and under
     # their impression cap (counts is a text => impressions map). In :cpm mode
     # the cpm drives the odds; if every eligible cpm is 0 we fall back to manual
-    # weights so selection never stalls. A pool with no eligible ads (or whose
-    # eligible weights sum to zero) falls back to the built-in list. Returns nil
-    # only when the pool is truly empty.
+    # weights so selection never stalls.
+    #
+    # Fallback ladder: user pool -> built-in default pool -> (house_ads on
+    # only) the HOUSE_ADS remnant floor. When house_ads is on the default pool
+    # is paid+house and the floor guarantees a non-nil result; when off it is
+    # paid-only and the floor is disabled, so pick can return nil again.
     #
     def self.pick(ads = DEFAULT_ADS, mode: :weight, now: Time.now, counts: {})
-      pool = eligible(normalize(ads), now, counts)
-      pool = eligible(normalize(DEFAULT_ADS), now, counts) if pool.empty? || pool.sum { |ad| ad[:weight] }.zero?
+      pool = drop_house(eligible(normalize(ads), now, counts))
+      pool = drop_house(eligible(normalize(paid_default_pool), now, counts)) if empty_pool?(pool)
+      pool = eligible(normalize(HOUSE_ADS), now, {}) if empty_pool?(pool) && house_ads?
+
+      return if pool.empty?
 
       key = SELECTION_MODES.include?(mode) ? mode : :weight
       key = :weight if key == :cpm && pool.sum { |ad| ad[:cpm] }.zero?
@@ -140,15 +216,65 @@ module SponsoredLogs
       weighted_pick(pool, key)
     end
 
+    # The built-in fallback pool. Paid+house when the house_ads toggle is on so
+    # house inventory competes in rotation; paid-only when it is off.
+    #
+    def self.paid_default_pool
+      house_ads? ? DEFAULT_ADS : PAID_ADS
+    end
+
+    # Texts that identify house inventory, used to exclude house ads from
+    # selection when the toggle is off (they can arrive via a user-supplied
+    # DEFAULT_ADS pool, not just the fallback).
+    #
+    HOUSE_TEXTS = HOUSE_ADS.map { |ad| ad[:text] }.freeze
+
+    # Strip house creatives from a pool when the house_ads toggle is off; a
+    # no-op when it is on. Keeps house ads out of rotation everywhere, not just
+    # the fallback tier.
+    #
+    def self.drop_house(pool)
+      return pool if house_ads?
+
+      pool.reject { |ad| HOUSE_TEXTS.include?(ad[:text]) }
+    end
+
+    # Whether the self-sponsoring house-ad inventory is enabled. Defaults to on
+    # when no configuration is present (e.g. direct .pick use in isolation).
+    #
+    def self.house_ads?
+      config = SponsoredLogs.configuration
+      config.respond_to?(:house_ads) ? config.house_ads != false : true
+    end
+
+    def self.empty_pool?(pool)
+      pool.empty? || pool.sum { |ad| ad[:weight] }.zero?
+    end
+
     def self.eligible(pool, now, counts)
       pool.select { |ad| eligible?(ad, now, counts[ad[:text]].to_i) }
     end
 
-    def self.render(entry, prefix = "[AD]")
+    # Render a normalized ad. :text ads (the default) stay byte-identical to
+    # the classic tagged line; :banner ads draw a word-wrapped box (see
+    # Banner) with the prefix embedded in the top border. When color is true
+    # the prefix is gilded in ANSI gold; the caller (emit) owns that decision
+    # because only it knows the output target's TTY-ness.
+    #
+    def self.render(entry, prefix = "[AD]", ascii_only: false, color: false)
       return if entry.nil?
 
       prefix = prefix.to_s.strip
-      prefix.empty? ? entry[:text] : "#{prefix} #{entry[:text]}"
+      return Banner.render(entry, prefix, ascii_only, color: color) if entry[:format] == :banner
+      return entry[:text] if prefix.empty?
+
+      "#{Color.colorize(prefix, enabled: color)} #{entry[:text]}"
+    end
+
+    # Delegated to Banner so the wrapper is testable in isolation.
+    #
+    def self.wrap_text(text, width)
+      Banner.wrap_text(text, width)
     end
 
     def self.weighted_pick(pool, key)

data/lib/sponsored_logs/banner.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  # Premium box-drawn ad inventory: the multi-line :banner placement. Turns a
+  # single ad line into above-the-fold, framed real estate in your stdout.
+  #
+  module Banner
+    # Body width, in columns, of a banner placement.
+    #
+    WIDTH = 60
+
+    # Glyph sets per impact tier + ascii_only fallback, ordered
+    # [top-left, top-right, bottom-left, bottom-right, horizontal, vertical].
+    #
+    GLYPHS = {
+      light: %w[┌ ┐ └ ┘ ─ │],
+      heavy: %w[┏ ┓ ┗ ┛ ━ ┃],
+      double: %w[╔ ╗ ╚ ╝ ═ ║],
+      ascii: %w[+ + + + - |]
+    }.freeze
+
+    # Draw the frame for one ad. ascii_only overrides whatever impact tier was
+    # purchased with the plain +/-/| fallback set. Inner span matches
+    # "<vert> <60 cols> <vert>" so every corner and edge lines up.
+    #
+    def self.render(entry, prefix, ascii_only, color: false)
+      top, top_r, bot, bot_r, horiz, vert = GLYPHS[ascii_only ? :ascii : (entry[:box] || :light)]
+      span = WIDTH + 2
+
+      body = wrap_text(entry[:text].to_s, WIDTH).map do |line|
+        "#{vert} #{line.ljust(WIDTH)} #{vert}"
+      end
+
+      corners = [top, top_r, horiz]
+      [top_border(prefix, corners, span, color: color), *body, "#{bot}#{horiz * span}#{bot_r}"].join("\n")
+    end
+
+    # Top border with the prefix embedded as "<h> [AD] <h-fill>". A blank
+    # prefix collapses to a solid rule (no gap, no tag). The fill math is
+    # computed against the PLAIN prefix, then the gilded tag is swapped in --
+    # ANSI escapes are zero-width, so gilding must not shift the border count.
+    # corners is [top-left, top-right, horizontal].
+    #
+    def self.top_border(prefix, corners, span, color: false)
+      corner, corner_r, horiz = corners
+      return "#{corner}#{horiz * span}#{corner_r}" if prefix.empty?
+
+      tag = " #{prefix} "
+      fill = horiz * (span - 1 - tag.length)
+      gilded = " #{Color.colorize(prefix, enabled: color)} "
+      "#{corner}#{horiz}#{gilded}#{fill}#{corner_r}"
+    end
+
+    # Word-wrap text to width columns, breaking a single word longer than the
+    # width mid-word. Always returns at least one (possibly blank) line.
+    #
+    def self.wrap_text(text, width)
+      lines = []
+      current = +""
+
+      text.to_s.split(/\s+/).each do |word|
+        word = word.dup
+        while word.length > width
+          lines << current unless current.empty?
+          current = +""
+          lines << word[0, width]
+          word = word[width..]
+        end
+
+        candidate = current.empty? ? word : "#{current} #{word}"
+        if candidate.length > width
+          lines << current
+          current = word
+        else
+          current = candidate
+        end
+      end
+
+      lines << current
+      lines.reject!(&:empty?)
+      lines.empty? ? [""] : lines
+    end
+  end
+end