lingara-apps 0.1.0.pre.alpha.7 → 0.1.0.pre.alpha.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f5af9193d43817ba4dc8a956472f9f8d5a4b4ed452bf68ba5a7eeba6ed118f2
-  data.tar.gz: a8ab344bc3dbb8135b3f45a268c632db50b0c74cf6dd8d1f5be37000d19145af
+  metadata.gz: fae6d6a2fd0f2ae63a10dfff6f337314be85565d58879160eb6b82b253cf072f
+  data.tar.gz: 7d10086620a5c492ed5c0c1f4afe2053424e0025dd6a55d8feeb02eaa336fc27
 SHA512:
-  metadata.gz: e37178ec1db06e8ca8352be6533a451f9cb783b6fc4836553fdd41dfea40025d9f1707f0b0888a0e23e33d1c79a61df2081a8bd0c9fd3244597d93216254abb3
-  data.tar.gz: 4c5a34c35af04aef932084bf412a6e51e1993338bf3b765dd17dd4553d9569b79089a8bddd596836c58e4c5a510b2cab09ae207ab126b71f132e64ed04e1093b
+  metadata.gz: e45e022cd0ee72996eed2809a5326057c3134fed1daad61eb172866dd49717e5e7e4f53209c02fbc3e13c9680ac7cac03dd791c91956c52be939d9b4f9d8c4d7
+  data.tar.gz: 9b20d6bd685e927ce7e8ace71ec76a6b45ee9a06ffd9eaacc2bb44a5457f468245f6038907794aa3558e499148709ae71c3883e1f15e607025e646222554b3d5

data/README.md

@@ -101,6 +101,47 @@ you want one; the kit never calls it for you.
 breaks, and `to_json` writes `manifest.json`. A bare `name("…")` is the name
 in the default locale.
 
+The listing can also carry `.long_description(…)`,
+`.developer(name:, url: nil, support_url: nil)` and
+`.image(sha256, "hero" | "screenshot", alt)`. An image is uploaded in the
+console or the CLI first and named here by `Lingara::Apps.image_sha256(bytes)`.
+These fields need a Lingara that knows them (ADR 16.10.26ah); a manifest that
+sets none of them is unaffected.
+
+## Localising your card
+
+Every request carries the learner's `locale`. Build one catalogue at startup
+and look strings up per request:
+
+```ruby
+MESSAGES = Lingara::Apps::Messages.new(default_locale: "en", catalogue: {
+  "en" => {"heading" => "Today's five", "done" => "Done ({count})"},
+  "zh-Hans" => {"heading" => "今日五词"}
+})
+
+t = MESSAGES.for(request.locale)
+Lingara::Apps.card.heading(t.t("heading"), 1).button(t.t("done", "count" => "3"), "done").build
+```
+
+- `Messages.new` raises `Lingara::Apps::MessagesError` at startup for a broken
+  catalogue, its `code` one of `:locale_invalid`, `:locale_duplicate`,
+  `:default_locale_missing`, `:key_missing_in_default`, never mid-render.
+- The locale is chosen by `Lingara::Apps.pick_locale`: an exact match, then
+  the request with its last subtag dropped, then the default. `zh-Hans` never
+  falls to `zh-Hant`; key your catalogue by Lingara's spellings (bare
+  subtags, plus `zh-Hans` and `zh-Hant`).
+- A key missing in the chosen locale falls back to the default's text, and an
+  unknown key returns the key, so a half-translated catalogue still renders a
+  whole card. `{name}` placeholders take String parameters; format numbers
+  and dates yourself with `t.locale`.
+- Never choose the UI language from the `languages` context slice: that is
+  the learner's study pair.
+
+A listing in one language only builds, with a warning: `builder.warnings`
+(or `Lingara::Apps.manifest_warnings(json)`) is `[:single_locale]` when
+`name` and `description` share no locale beyond the default. The kit never
+prints it.
+
 ## Things to know
 
 - **The user agent.** Lingara's requests carry

data/lib/lingara/apps/i18n.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Apps
+    # Localising a card (ADR 16.10.26aj, contract AK6): one locale pick, a
+    # message catalogue checked when built and quiet when used, and the
+    # listing's derived locales and warnings. Every answer here is pinned by
+    # conformance/vectors/locales.json and manifest-warnings.json, so the
+    # seven kits agree. Nothing here prints or logs: that is the caller's.
+
+    # A catalogue Messages.new refuses, at startup rather than mid-render.
+    # #code is one of CODES, in the order they are checked.
+    class MessagesError < StandardError
+      CODES = %i[locale_invalid locale_duplicate default_locale_missing key_missing_in_default].freeze
+
+      attr_reader :code
+
+      def initialize(code)
+        @code = code
+        super("the message catalogue is refused: #{code}")
+      end
+    end
+
+    # A message catalogue: locale => key => text, checked when built.
+    #
+    #   messages = Lingara::Apps::Messages.new(default_locale: "en", catalogue: {
+    #     "en" => {"greeting" => "Hello, {name}", "bye" => "Goodbye"},
+    #     "ja" => {"greeting" => "こんにちは、{name}"}
+    #   })
+    #   t = messages.for(request.locale)
+    #   t.t("greeting", "name" => "Ana") # also t.call(…) or t.(…)
+    #   t.locale                         # the chosen locale, safe for a text element's lang
+    #
+    # Locales and keys may be Strings or Symbols; both are read as Strings.
+    class Messages
+      # One locale's lookup. A key missing in the chosen locale falls to the
+      # default locale's text; an unknown key returns the key itself. Never
+      # raises.
+      class Lookup
+        PLACEHOLDER = /\{([A-Za-z0-9_]+)\}/
+
+        # The chosen locale, safe for a text element's `lang`.
+        attr_reader :locale
+
+        def initialize(locale, table, fallback)
+          @locale = locale
+          @table = table
+          @fallback = fallback
+        end
+
+        # The text for +key+, its `{name}` placeholders replaced in one pass by
+        # the String parameter of that name. An unknown or unsupplied one, or
+        # one whose value is not a String, stays literal: format numbers and
+        # dates yourself, with #locale.
+        def t(key, params = {})
+          key = key.to_s
+          text = @table.fetch(key) { @fallback.fetch(key, key) }
+          values = params.to_h.transform_keys(&:to_s)
+          text.gsub(PLACEHOLDER) do |whole|
+            value = values[Regexp.last_match(1)]
+            value.is_a?(String) ? value : whole
+          end
+        end
+
+        alias_method :call, :t
+      end
+
+      attr_reader :default_locale
+
+      # Raises MessagesError for a broken catalogue.
+      def initialize(default_locale:, catalogue:)
+        @default_locale = default_locale.to_s
+        @catalogue = catalogue.to_h.to_h do |locale, table|
+          [locale.to_s, table.to_h.to_h { |key, text| [key.to_s, text.to_s] }]
+        end
+        code = refusal
+        raise MessagesError, code if code
+      end
+
+      # The catalogue's locales, in its own order and spelling.
+      def locales = @catalogue.keys
+
+      # The lookup for a request's `locale`, picked over the catalogue's locales.
+      def for(requested)
+        locale = Apps.pick_locale(requested, locales, @default_locale)
+        Lookup.new(locale, @catalogue.fetch(locale), @catalogue.fetch(@default_locale))
+      end
+
+      private
+
+      def refusal
+        return :locale_invalid unless (locales + [@default_locale]).all? { |l| l.match?(Limits::LANG_PATTERN) }
+        return :locale_duplicate if locales.map { |l| I18n.normal(l) }.uniq.size != locales.size
+        fallback = @catalogue[@default_locale]
+        return :default_locale_missing if fallback.nil?
+        :key_missing_in_default unless @catalogue.each_value.all? { |table| table.keys.all? { |k| fallback.key?(k) } }
+      end
+    end
+
+    # The helpers' shared parts.
+    module I18n
+      module_function
+
+      # A locale as the pick compares it: `_` read as `-`, case-folded.
+      def normal(locale)
+        locale.tr("_", "-").downcase
+      end
+
+      def keys(value)
+        value.is_a?(Hash) ? value.keys : []
+      end
+    end
+
+    # The closed list of manifest warning codes; one member in v1.
+    MANIFEST_WARNINGS = %i[single_locale].freeze
+
+    module_function
+
+    # The available locale for +requested+, in its available spelling: an
+    # exact match (case-insensitive, `_` read as `-`), then +requested+ with
+    # its last subtag dropped, repeated, then +default_locale+. The chain
+    # never widens: `pt` does not match `pt-BR`, and `zh-Hans` never reaches
+    # `zh-Hant`. Never raises; a nil, empty or non-String +requested+ is the
+    # default.
+    def pick_locale(requested, available, default_locale)
+      return default_locale unless requested.is_a?(String) && !requested.empty?
+      spelled = {}
+      available.each { |locale| spelled[I18n.normal(locale)] ||= locale }
+      candidate = I18n.normal(requested)
+      loop do
+        return spelled[candidate] if spelled.key?(candidate)
+        cut = candidate.rindex("-")
+        return default_locale if cut.nil?
+        candidate = candidate[0, cut]
+      end
+    end
+
+    # The locales the listing is translated into: where `name` and
+    # `description` both have an entry, and `long_description` too when
+    # present and not nil, sorted by byte order. [] for a manifest
+    # validate_manifest refuses.
+    def manifest_locales(manifest)
+      return [] if ManifestRules.first_broken(manifest)
+      long = manifest["long_description"]
+      I18n.keys(manifest["name"]).select do |locale|
+        I18n.keys(manifest["description"]).include?(locale) && (long.nil? || I18n.keys(long).include?(locale))
+      end.sort_by(&:b)
+    end
+
+    # What the listing could do better, never a refusal: [:single_locale]
+    # when it is translated into its default locale alone. [] for a refused
+    # manifest.
+    def manifest_warnings(manifest)
+      locales = manifest_locales(manifest)
+      (locales.size == 1 && locales.first == manifest["default_locale"]) ? [:single_locale] : []
+    end
+  end
+end

data/lib/lingara/apps/listing.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Lingara
+  module Apps
+    # The listing's three optional manifest fields (ADR 16.10.26aj D4), each
+    # rule mirroring Backend ADR 16.10.26ah D2–D5: `long_description`,
+    # `developer` and `images`, and the `locales` key a manifest never
+    # declares. A nil long_description, developer, url or support_url reads
+    # as absent; a nil images is refused.
+    module ListingRules
+      LONG_DESCRIPTION_MAX_CHARS = 1500
+      DEVELOPER_NAME_MAX_CHARS = 60
+      IMAGE_ALT_MAX_CHARS = 140
+      MAX_HERO_IMAGES = 1
+      MAX_SCREENSHOTS = 5
+      IMAGE_ROLES = %w[hero screenshot].freeze
+
+      # Zero-width characters, beyond the card rules' controls and bidi marks.
+      ZERO_WIDTH = /[​-‏]/
+      SHA256_HEX = /\A[0-9a-f]{64}\z/
+
+      module_function
+
+      # One text: 1..max scalar values after trimming, none of the name
+      # rule's characters (`\n` aside when +newlines+, which also refuses a
+      # run of three `\n` in the untrimmed value).
+      def plain_text?(value, max, newlines = false)
+        return false unless value.is_a?(String)
+        trimmed = Limits.trim(value)
+        return false if newlines && value.include?("\n\n\n")
+        trimmed.length.between?(1, max) && !Limits.control?(trimmed, newlines) && !trimmed.match?(ZERO_WIDTH)
+      end
+
+      # A non-empty locale map whose every value is plain_text?.
+      def localized?(value, max, newlines = false)
+        value.is_a?(Hash) && !value.empty? && value.each_value.all? { |v| plain_text?(v, max, newlines) }
+      end
+
+      # A locale map holding +default_locale+, as AE-1 requires of the listing's maps.
+      def localized_with_default?(value, default_locale, max, newlines = false)
+        localized?(value, max, newlines) && default_locale.is_a?(String) && value.key?(default_locale)
+      end
+
+      def long_description?(m)
+        value = m["long_description"]
+        value.nil? || localized_with_default?(value, m["default_locale"], LONG_DESCRIPTION_MAX_CHARS, true)
+      end
+
+      def developer?(m)
+        value = m["developer"]
+        return true if value.nil?
+        return false unless value.is_a?(Hash) && plain_text?(value["name"], DEVELOPER_NAME_MAX_CHARS)
+        [value["url"], value["support_url"]].all? { |u| u.nil? || (u.is_a?(String) && Limits.safe_link?(u)) }
+      end
+
+      def image?(entry, default_locale)
+        entry.is_a?(Hash) && entry["sha256"].is_a?(String) && entry["sha256"].match?(SHA256_HEX) &&
+          IMAGE_ROLES.include?(entry["role"]) && localized_with_default?(entry["alt"], default_locale, IMAGE_ALT_MAX_CHARS)
+      end
+
+      def images?(m)
+        return true unless m.key?("images")
+        value = m["images"]
+        return false unless value.is_a?(Array) && value.all? { |e| image?(e, m["default_locale"]) }
+        roles = value.map { |e| e["role"] }
+        roles.count("hero") <= MAX_HERO_IMAGES && roles.count("screenshot") <= MAX_SCREENSHOTS &&
+          value.map { |e| e["sha256"] }.uniq.size == value.size
+      end
+
+      # `locales` is derived by Lingara, so a manifest that declares it is refused.
+      def locales_absent?(m)
+        !m.key?("locales")
+      end
+
+      # The listing keys the stored manifest carries when set: nil and an
+      # empty images are absent.
+      def stored(m)
+        out = {}
+        %w[long_description developer].each { |key| out[key] = m[key] unless m[key].nil? }
+        out["images"] = m["images"] if m["images"].is_a?(Array) && !m["images"].empty?
+        out
+      end
+    end
+
+    module_function
+
+    # The lowercase hex SHA-256 of an image's bytes (a String, read as
+    # binary), the hash its upload is stored under.
+    def image_sha256(bytes)
+      Digest::SHA256.hexdigest(bytes)
+    end
+  end
+end

data/lib/lingara/apps/manifest.rb

@@ -25,7 +25,8 @@ module Lingara
       DESCRIPTION_MAX_CHARS = 280
       STORED_MAX_BYTES = 65_536
 
-      RULES = %i[manifest_version default_locale name description render_url slots context duplicate too_large].freeze
+      RULES = %i[manifest_version default_locale name description render_url slots context long_description developer
+        images locales duplicate too_large].freeze
 
       # The slots a manifest may name: the generated AppSlotName's values,
       # without the generator's unknown-value placeholder.
@@ -65,13 +66,14 @@ module Lingara
         %w[slots context scopes].any? { |k| m[k].is_a?(Array) && m[k].uniq.size != m[k].size }
       end
 
-      # The compact UTF-8 JSON of the seven stored keys, defaults filled.
+      # The compact UTF-8 JSON of the seven stored keys, defaults filled, and
+      # the listing's keys when set.
       def stored_bytes(m)
         stored = {
           "default_locale" => m["default_locale"], "name" => m["name"], "description" => m["description"],
           "slots" => m["slots"], "context" => m["context"] || [], "scopes" => m["scopes"] || [],
           "tutor_note" => m["tutor_note"].nil? ? false : m["tutor_note"]
-        }
+        }.merge(ListingRules.stored(m))
         JSON.generate(stored).bytesize
       end
 
@@ -83,6 +85,10 @@ module Lingara
         render_url: ->(m) { m["render_url"].is_a?(String) && m["render_url"].match?(RENDER_URL) },
         slots: ->(m) { within?(m, "slots", SLOT_NAMES, false) },
         context: ->(m) { within?(m, "context", CONTEXT_SLICE_KINDS, true) },
+        long_description: ->(m) { ListingRules.long_description?(m) },
+        developer: ->(m) { ListingRules.developer?(m) },
+        images: ->(m) { ListingRules.images?(m) },
+        locales: ->(m) { ListingRules.locales_absent?(m) },
         duplicate: ->(m) { !duplicate?(m) },
         too_large: ->(m) { stored_bytes(m) <= STORED_MAX_BYTES }
       }.freeze
@@ -110,6 +116,9 @@ module Lingara
         @scopes = []
         @tutor_note = false
         @listed = false
+        @long_description = nil
+        @developer = nil
+        @images = []
       end
 
       def default_locale(locale) = set(:@default_locale, locale)
@@ -136,17 +145,38 @@ module Lingara
       # Whether the app appears in the catalogue; false unless set.
       def listed(listed = true) = set(:@listed, listed)
 
+      # The listing's longer text: plain, paragraphs split on blank lines. A
+      # locale map, or a bare String meaning the default locale's.
+      def long_description(text) = set(:@long_description, text)
+
+      # Who made the app, shown on its listing as the developer's own claim.
+      def developer(name:, url: nil, support_url: nil)
+        set(:@developer, {"name" => name, "url" => url, "support_url" => support_url}.compact)
+      end
+
+      # An image already uploaded in the console or the CLI, named by
+      # Lingara::Apps.image_sha256 of its bytes; +role+ is "hero" or
+      # "screenshot", +alt+ a locale map or a bare String.
+      def image(sha256, role, alt)
+        @images << [sha256, role.to_s, alt]
+        self
+      end
+
       # The manifest, or ManifestError naming the first rule it breaks.
       def build
-        manifest = {
-          "manifest_version" => 1, "default_locale" => @default_locale, "name" => localized(@name),
-          "description" => localized(@description), "render_url" => @render_url, "slots" => @slots.dup,
-          "context" => @context.dup, "scopes" => @scopes.dup, "tutor_note" => @tutor_note, "listed" => @listed
-        }
+        manifest = wire
         Apps.validate_manifest(manifest)
         manifest
       end
 
+      # What the listing could do better, never a refusal; [] while the
+      # manifest would not build. Never raises.
+      def warnings = Apps.manifest_warnings(wire)
+
+      # The locales the listing is translated into; [] while the manifest
+      # would not build.
+      def locales = Apps.manifest_locales(wire)
+
       # The validated manifest as the JSON the console accepts as an upload.
       def to_json(*)
         "#{JSON.pretty_generate(build)}\n"
@@ -154,6 +184,24 @@ module Lingara
 
       private
 
+      def wire
+        {
+          "manifest_version" => 1, "default_locale" => @default_locale, "name" => localized(@name),
+          "description" => localized(@description), "render_url" => @render_url, "slots" => @slots.dup,
+          "context" => @context.dup, "scopes" => @scopes.dup, "tutor_note" => @tutor_note, "listed" => @listed
+        }.merge(listing)
+      end
+
+      def listing
+        out = {}
+        out["long_description"] = localized(@long_description) unless @long_description.nil?
+        out["developer"] = @developer.dup unless @developer.nil?
+        unless @images.empty?
+          out["images"] = @images.map { |sha, role, alt| {"sha256" => sha, "role" => role, "alt" => localized(alt)} }
+        end
+        out
+      end
+
       def set(ivar, value)
         instance_variable_set(ivar, value)
         self

data/lib/lingara/apps/version.rb

@@ -3,10 +3,10 @@
 module Lingara
   module Apps
     # This kit's released version, SemVer.
-    VERSION = "0.1.0-alpha.7"
+    VERSION = "0.1.0-alpha.8"
 
     # The same version in RubyGems' spelling, which the gemspec uses.
-    GEM_VERSION = "0.1.0.pre.alpha.7"
+    GEM_VERSION = "0.1.0.pre.alpha.8"
 
     # The API version the app view was generated from.
     GENERATED_FROM = "2026-10-virile-dragon"

data/lib/lingara/apps.rb

@@ -19,6 +19,8 @@ require_relative "apps/unions"
 require_relative "apps/operations"
 require_relative "apps/limits"
 require_relative "apps/card"
+require_relative "apps/listing"
+require_relative "apps/i18n"
 require_relative "apps/manifest"
 require_relative "apps/app"
 require_relative "apps/rack_app"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lingara-apps
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.7
+  version: 0.1.0.pre.alpha.8
 platform: ruby
 authors:
 - Spinning Cat Studios
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lingara
@@ -49,7 +49,9 @@ files:
 - lib/lingara/apps/generated/app_slot_name.rb
 - lib/lingara/apps/generated/button_style.rb
 - lib/lingara/apps/generated/card.rb
+- lib/lingara/apps/i18n.rb
 - lib/lingara/apps/limits.rb
+- lib/lingara/apps/listing.rb
 - lib/lingara/apps/manifest.rb
 - lib/lingara/apps/operations.rb
 - lib/lingara/apps/rack_app.rb