openui-rails 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5365a84ab993b7d1d7efd392753a9699f28cbe17acd8482d517e0e529150a6c
-  data.tar.gz: d071e4fbd4f29fefd7a074f411b30cdd0b453bc5532410bbcb7af3333184f340
+  metadata.gz: 3d3b9295fd6e8fb6d3b284c0c66d80e3d02f01e7d1c09913f02acfd6ff183273
+  data.tar.gz: 9e5eb58014af64320ea178b05f63843f617f5fe3fa650e083f411a116a12dff2
 SHA512:
-  metadata.gz: cd3efcb1e979ac3c63892e83a68fcd1b62db7d44297763e2fdc451251220c823efa2f27afc25d340902e5f56e0c8b7c53afd952df115eda9e78c95a143b8bb0f
-  data.tar.gz: e8a972cb1ef2663d0247263984d06e82e24cfcf1e4e972788c3dc917a111c5ea88e8cd782191f7baf19d2804660ed93bd6c8241a58074010f112b22686ce6a55
+  metadata.gz: bcbbc65b5a3a3d66839d727e325238643973050b39248695e6623b4f45c7fd343ecea7cf52c8c59f70fe6caf63aace284c677d4cd50211ed4fef73e9fc984da7
+  data.tar.gz: 53147d0d353adf39e448f3ea82ac1c60dd1f7fee9168573d5802b052a3bd54fbd949fd9ac5b8d591ff134cc627c9204feeb07ffd1289304109b5eedd41ea08c0

data/AUDIT.md

@@ -4,10 +4,29 @@
 
 The audit found real defects despite the original green test suite. The fixes
 below have regression coverage. The owner authorized publication of `0.1.0`
-on 2026-10-18. Publication still requires the selected tag's complete CI to
-pass and the protected publishing workflow to succeed. This audit establishes
+on 2026-10-18. The exact tag's complete CI and protected publishing workflow
+passed, and `0.1.0` is published on RubyGems and GitHub. This audit establishes
 the specific behaviors below, not the absence of all bugs.
 
+## Publication evidence
+
+- Release tag `v0.1.0` points to commit
+  `e2203c0e0f573f1b8206d9abdac4ab8f838594b8`.
+- [Publishing run 39115168826](https://github.com/yorzi/openui-rails/actions/runs/39115168826)
+  passed the complete reusable CI suite, package checks, protected environment
+  approval, RubyGems upload, and GitHub release draft creation.
+- [RubyGems 0.1.0](https://rubygems.org/gems/openui-rails/versions/0.1.0) and
+  [GitHub Release v0.1.0](https://github.com/yorzi/openui-rails/releases/tag/v0.1.0)
+  expose the same artifact. SHA-256:
+  `275c124a9e8e9c82b471357e3f314e4c86d6255c8fc9ef0313be858525bffee5`.
+  The actual RubyGems download, GitHub asset, API digest, and `SHA256SUMS` match.
+- The downloaded RubyGems artifact passed the fresh Rails host probe: install
+  generator, eager load, and HTTP rendering.
+- [Documentation](https://openui-rails.wangyaodi.com/) uses GitHub Pages with
+  Actions. Cloudflare has a DNS-only CNAME to `yorzi.github.io`. GitHub verified
+  domain ownership through a TXT record and issued the certificate. HTTPS is
+  enforced. The release docs build checks stable and `/next/` channels.
+
 ## Confirmed defects corrected
 
 | Area | Defect | Correction and evidence |
@@ -71,8 +90,9 @@ complete accessibility, legal clearance, or an absence of future vulnerabilities
   `release`.
 - The repository is public. Security reports go to the address in `SECURITY.md`;
   public support uses GitHub Issues.
-- RubyGems has a pending Trusted Publisher for the exact workflow and
-  environment. The first successful publication activates the gem's publisher.
+- RubyGems Trusted Publishing for the exact workflow and environment was
+  successfully used for the first release. The public version page identifies
+  the GitHub Actions repository, workflow, and environment as its publisher.
 - The GitHub `release` environment requires approval by `yorzi`, allows the
   `main` branch only, and disallows administrator bypass. Self-review remains
   available for the single maintainer.

data/CHANGELOG.md

@@ -6,6 +6,55 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-19
+
+### Added
+
+- A packaged, opt-in support-ticket reference host with SQLite persistence,
+  importmap, HTTP Turbo Streams, real Query/Mutation calls, host-owned
+  conversation continuation, and scoped snapshot recovery.
+- `bin/check-reference` verifies the maintained host or a fresh host using only
+  the built artifact. Browser checks cover reload, lost envelopes, expired
+  identity, cross-tenant access, read-only roles, stale/duplicate actions, CSRF,
+  keyboard activation, and mobile layout. The reference host enables CSRF
+  itself, including during the documented test-environment review session.
+- `bin/check-release --candidate` validates unpublished candidate metadata
+  without weakening the publication gate.
+- `Surface` and `openui_surface` accept persisted `next_sequence` and
+  `completed` values to restore stream ordering after a page reload.
+
+### Fixed
+
+- Conversation actions preserve the official runtime's user message, form name,
+  and form state as validated-by-host action arguments. Strict
+  `continue_conversation` schemas need to allow the metadata they consume.
+
+## [0.2.0] - 2026-10-18
+
+### Added
+
+- `openui:library:prepare` installs prompt/spec exports of the exact pinned
+  default chat library and its upstream license without browser or Node tools.
+  Existing different files require explicit overwrite; outputs stay inside
+  the application root.
+- `openui:doctor` reports local configuration, default library identity,
+  runtime checksums, and action-route failures without writes or network calls.
+  Browser setup and host policy checks remain explicitly unverified.
+- Local `bin/check` and disposable `bin/check-browser` runners, with fixture
+  screenshots on both passing and failing tests and the same browser entry
+  point in CI.
+
+### Changed
+
+- The install generator leads with the default chat library and setup checks.
+  Custom libraries retain the pinned CLI path and require a matching runtime.
+
+### Fixed
+
+- Manifest name queries now read name-keyed collections used by the official
+  default-library spec, as well as the previously supported array format.
+  Fingerprint calculation is unchanged.
+
 ## [0.1.0] - 2026-10-18
 
 ### Fixed
@@ -67,5 +116,7 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Gem-scoped RubyGems Trusted Publishing through GitHub OIDC, with a protected
   release environment and verified artifact handoff.
 
-[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.1.0...main
+[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.3.0...main
+[0.3.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.3.0
+[0.2.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.2.0
 [0.1.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.1.0

data/CONFIGURATION.md

@@ -1,79 +1,11 @@
 # Configuration
 
-Configure the bridge in `config/initializers/openui.rb`. Rails owns identity,
-authorization, stream subscriptions, persistence, and snapshot recovery.
-
-| Setting | Default | Contract |
-| --- | --- | --- |
-| `transport` | `:turbo` | Factory preference: `:turbo`, `:action_cable`, or `:none`. Pass it explicitly to `Transports.build`; it does not create a subscription. |
-| `library_spec_path` | `nil` | JSON manifest from the exact runtime library. Enables server and browser fingerprint checks. |
-| `prompt_path` | `nil` | Prompt generated from that same library. |
-| `runtime_assets` | `:self_hosted` | Use `:external` only with explicit exact-version URLs. |
-| `local_runtime_path` | `"/openui"` | Public URL directory for self-hosted assets. |
-| `runtime_version` | pinned `0.2.1` | The fetch task accepts only the checksum-locked version. Other versions are unverified. |
-| `runtime_url` | derived self-hosted JS URL | Explicit override for a host-built or external runtime. |
-| `runtime_integrity` | pinned hash for the default runtime | Override for another JS asset. No default hash is assumed for custom URLs. |
-| `runtime_stylesheet_url` | derived self-hosted CSS URL | Required when using `:external` and `openui_stylesheet_tag`. |
-| `runtime_stylesheet_integrity` | pinned hash for the default runtime | Override for another CSS asset. |
-| `actions_endpoint` | `"/openui-rails/actions"` | Must match the host engine mount. |
-| `stream_byte_limit` | `1_048_576` | Positive integer; enforced by server writer and browser. |
-| `pending_byte_limit` | `32_768` | Positive byte-based flush threshold, at most the stream limit. Lower it for smaller, more frequent updates. There is no timer-based flush. |
-| `idempotency_ttl` | `900` seconds | Finite positive number. Replays are protected only within the store's lifetime and TTL. |
-| `idempotency_store` | process-local `MemoryStore` | Use a shared atomic store for multiple processes. See the contract below. |
-| `idempotency_scope` | derived actor/tenant identity | Optional callable receiving `Invocation`; return a stable, JSON-serializable namespace for custom identity types. |
-| `actor_resolver` | host `current_user`, if available | Callable receiving the engine controller. Host authentication filters are inherited. |
-| `surface_resolver` | `nil` | Callable `(surface_id, actor:, context:)`; return the scoped surface, or `nil` to deny. Without it, the authorizer owns resource/version checks. |
-| `authorize_action` | `nil` | Global authorizer receiving `Invocation`. Missing authorization denies the action. Per-action `authorize:` takes precedence. |
-| `on_error` | `nil` | Server stream-error hook `(error, message_id:)`. Do not log credentials or unredacted provider requests. |
-| `action_registry` | lazy `Actions::Registry` | Allowlisted action definitions. |
-
-`library_name` and `surface_id_param` are legacy metadata settings. They do not
-select a runtime library or change the endpoint's `surface_id` wire key.
-
-After you create the library files, call
-`OpenUI::Rails.configuration.validate!` to check required configuration and
-read the actual manifest and configured prompt files.
-Boot does not call it automatically, so setup tasks can run before files exist.
-
-## Shared idempotency store
-
-The dispatcher supplies a SHA-256 key scoped to server actor and tenant identity.
-It supplies a digest of the entire validated request separately.
-
-```ruby
-claim(key, ttl:, digest:)
-# => [:claimed, nil, digest, claim_token]       # this request owns execution
-# => [:pending, nil, stored_digest, token]     # execution is in progress
-# => [:replay, result, stored_digest, token]   # completed, including nil/false
-
-record(key, result, claim_token: token)
-```
-
-Implement `claim` atomically. Make `claim_token` unique for every new claim.
-Ignore a `record` call whose token no longer owns the key. Preserve completed
-`nil` and `false` results instead of treating them as pending.
-
-The default identity is `[class, id]` for records and `[class, value]` for scalar
-identities. Unsupported identity objects need `idempotency_scope`. Scope must
-come from trusted server state, not a client-supplied user or tenant ID.
-
-A failed handler leaves a pending claim until expiry because its side effects
-may already have happened. A handler that outlives the TTL can overlap a later
-claim. Choose a suitable TTL and enforce business-level uniqueness or
-transactions for irreversible operations. Process-local memory does not survive
-restarts and cannot coordinate separate workers.
-
-## Browser errors and recovery
-
-Listen for `openui:error` to show a host-owned error or fallback. Listen for
-`openui:snapshot-required` to fetch an authorized, authoritative snapshot.
-The bridge emits these events; it does not implement the host's fallback UI,
-snapshot endpoint, reconnection policy, or persistence.
-
-The action bridge rejects authentication redirects and non-JSON, malformed, or
-mismatched results. An expired-session redirect emits `unauthorized`; a broken
-response contract emits `invalid_response`. Host callbacks may still redirect
-HTTP requests, but a redirect is never a successful JSON action result.
-
-Configure a matching manifest in production. Without one, the bridge cannot
-verify that the model prompt, stored output, and runtime library agree.
+Use the [configuration guide](https://openui-rails.wangyaodi.com/configuration/)
+for settings, defaults, and the shared idempotency-store contract.
+Review [production setup](https://openui-rails.wangyaodi.com/production/)
+before deploying.
+
+The site documents the latest release. For `main`, use
+[/next/configuration/](https://openui-rails.wangyaodi.com/next/configuration/).
+To read offline, open the [guide source](docs/_getting_started/configuration.md)
+at the tag matching your installed gem.

data/CONTRIBUTING.md

@@ -14,12 +14,18 @@ bundle exec bin/rails db:test:prepare
 
 ## Before you open a pull request
 
+Use `bin/check` for the local lint, unit/integration, RubyLLM, and built-gem
+checks. Add `--browser` for deterministic browser tests and `--docs` for the
+versioned site build. For the real runtime, fetch its pinned assets explicitly
+and pass `--runtime tmp/real-runtime`. See [agent verification](DEVELOPMENT.md)
+for focused runs, screenshots, and test boundaries.
+
 ```bash
 bundle exec bin/rails test        # unit + integration tests
 bundle exec bin/rails test:system # browser (system) tests, needs Chrome
 bundle exec rubocop               # style (rubocop-rails-omakase)
 bundle exec gem build openui-rails.gemspec
-bundle exec ruby bin/smoke-package openui-rails-0.1.0.gem
+bundle exec ruby bin/smoke-package openui-rails-0.3.0.gem
 bundle exec bundler-audit check --update
 bundle exec ruby -Itest test/compatibility/ruby_llm_smoke.rb
 ```
@@ -57,6 +63,28 @@ cases.
   prompt CLI; pin exact versions.
 - Write commit messages that explain the *why*.
 
+## Documentation
+
+Keep the README as a short introduction and navigation page. Write setup,
+configuration, feature guides, and API contracts in `docs/`; the root
+`CONFIGURATION.md` and `UPGRADING.md` link there. Keep contributor instructions,
+security policy, release procedures, and audit evidence in the repository.
+
+Use [ROADMAP.md](ROADMAP.md) for proposed work toward 1.0. Record delivered
+changes in [CHANGELOG.md](CHANGELOG.md). A planned API is not a supported API.
+Update the relevant guide with each public API change and add migration steps
+when existing applications need changes.
+
+Build documentation before submitting it:
+
+```sh
+docs/bin/build.sh
+```
+
+The build includes the release docs at `/` and your working tree at `/next/`.
+Preview with `docs/bin/serve.sh`; it binds to `127.0.0.1:4000`. Stop it when you
+finish reviewing.
+
 ## Reporting security issues
 
 Please do not open a public issue for a security problem. See `SECURITY.md`.

data/DEVELOPMENT.md

@@ -0,0 +1,89 @@
+# Development and verification
+
+Use `test/dummy` as the maintained local host. Temporary generated hosts verify
+the built gem. Keep examples synthetic and provider-free unless a task explicitly
+authorizes a live call. Follow this loop for each feature:
+
+1. Reproduce the behavior with a focused test through its public entry point.
+2. Implement the change and update its guide in the same commit.
+3. Run the focused checks, then `bin/check`. Run database suites sequentially.
+4. For browser behavior, run the relevant suite, inspect its screenshots, and
+   use browser tools for keyboard, layout, or mobile questions left unresolved.
+5. Commit a completed unit with its actual verification results. Stop any
+   task-owned service before finishing.
+
+## Reference workflow
+
+```sh
+bin/check-reference
+bin/check-reference --runtime tmp/real-runtime
+bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+# Focus one browser scenario:
+bin/check-reference --runtime tmp/real-runtime --name test_a_lost_turbo_envelope_recovers_from_the_scoped_snapshot
+```
+
+The first command verifies reference-host transactions in a temporary SQLite
+database. The browser option uses the real renderer and screenshot evidence.
+The gem option generates an isolated consumer using the example packaged in
+that artifact; it imports no dummy-app fixtures. `bin/check --runtime` includes
+this consumer flow. CI runs the host transaction tests in its Ruby/Rails matrix
+and the artifact browser flow in the system job.
+
+Add `--host tmp/support-desk` with `--gem` to retain a synthetic review host.
+It refuses existing directories and starts no persistent service. Follow the
+site's Reference Workflow guide for its explicit loopback review command.
+
+## Checks
+
+```sh
+bin/check
+bin/check --browser --docs
+# Requires npm and network only for this explicit fetch:
+bundle exec rake "app:openui:runtime:fetch[$PWD/tmp/real-runtime]"
+bin/check-browser --runtime tmp/real-runtime
+# Run all local checks including both browser layers:
+bin/check --runtime tmp/real-runtime --docs
+# Focus on one browser test file:
+bin/check-browser test/system/openui_confirmation_system_test.rb
+```
+
+Chrome is required. Set `CHROME_BIN` for a nonstandard executable. Selenium
+manages the driver; its first run may need a download. Each browser run uses a
+temporary SQLite database and stores passed and failed fixture screenshots in
+the printed `tmp/browser/` directory. Screenshots are evidence for visual
+review, not a substitute for assertions. Logs, databases, and screenshots stay
+in ignored directories. Do not put production data in them.
+
+The Capybara server and driver port probe bind loopback. Test processes close
+their browser sessions and remove the temporary database on exit. This is not
+a browser network sandbox. The stub suite exercises bridge failure cases; the
+real-runtime suite verifies the pinned renderer, library identity, actions,
+tools, and keyboard behavior. Neither proves live-provider compatibility.
+
+## Refresh the default library exports
+
+When changing the pinned runtime, regenerate from its checksum-verified bundle:
+
+```sh
+bin/export-default-library tmp/real-runtime
+bin/export-default-library tmp/real-runtime --check
+```
+
+This maintainer command uses the existing Selenium/Chrome development tools,
+closes the browser afterward, and preserves the upstream license and provenance.
+Review the generated files and run the real-runtime tests. Applications use the
+exported files inside the gem and need none of these browser tools for preparation.
+
+## Installed artifact and release checks
+
+`bin/check` builds into `tmp/package/` and tests a new Rails host using that
+artifact. It verifies default library preparation, repeat runs, overwrite
+rejection, missing-setup doctor exits, eager load, and HTTP mount rendering.
+With `--runtime`, it also verifies a successful doctor report, actual rendering,
+an explicitly authorized CSRF-protected action, and a 390px mobile page in a
+fresh host. The host reads its prompt/spec from the gem, never test fixtures.
+Fixture screenshots use the same `tmp/browser/` tree. CI runs this path too.
+This does not establish external adoption or remote CI success.
+Dependency-advisory refreshes remain explicit network operations; run
+`bundle exec bundler-audit check --update` before a release. Follow
+[Releasing](RELEASING.md) for the remaining publication checks.