Merge pull request #21 from crup/chore/runtime-hardening-release

feat: harden runtime contract and release flow

Author: crup

.github/workflows/release.yml

@@ -212,9 +212,12 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       package_version: ${{ steps.version.outputs.package_version }}
+      release_target: ${{ steps.persist.outputs.release_target }}
     steps:
       - name: Checkout main
         uses: actions/checkout@v6
+        with:
+          ref: main
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
@@ -259,13 +262,33 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Persist released version to main
+        id: persist
+        env:
+          STABLE_VERSION: ${{ needs.guard.outputs.stable_version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          if git diff --quiet -- package.json; then
+            echo "release_target=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git add package.json
+          git commit -m "chore(release): v$STABLE_VERSION"
+          git push origin HEAD:main
+          echo "release_target=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
   github-release:
     name: 4. Create GitHub release
     needs: [guard, publish]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout main
         uses: actions/checkout@v6
+        with:
+          ref: main
 
       - name: Create GitHub release
         env:
@@ -288,7 +311,7 @@ jobs:
           gh release create "v$STABLE_VERSION" \
             --title "v$STABLE_VERSION" \
             --notes-file release-notes.md \
-            --target "${{ github.sha }}"
+            --target "${{ needs.publish.outputs.release_target }}"
 
       - name: Release summary
         run: |

README.md

@@ -2,13 +2,14 @@
 
 [![npm version](https://img.shields.io/npm/v/%40crup%2Fport?color=1f8b4c)](https://www.npmjs.com/package/@crup/port)
 [![npm downloads](https://img.shields.io/npm/dm/%40crup%2Fport?color=0b7285)](https://www.npmjs.com/package/@crup/port)
+[![bundle size](https://deno.bundlejs.com/badge?q=%40crup%2Fport)](https://bundlejs.com/?q=%40crup%2Fport)
 [![License](https://img.shields.io/github/license/crup/port?color=495057)](https://github.com/crup/port/blob/main/LICENSE)
 [![CI](https://github.com/crup/port/actions/workflows/ci.yml/badge.svg)](https://github.com/crup/port/actions/workflows/ci.yml)
 [![Docs](https://github.com/crup/port/actions/workflows/docs.yml/badge.svg)](https://github.com/crup/port/actions/workflows/docs.yml)
 
 Protocol-first iframe runtime for explicit host/child communication.
 
-`@crup/port` exists for the part of embedded app work that usually rots first: lifecycle, handshake timing, and message discipline. It gives the host page a small runtime for mounting an iframe, opening it inline or in a modal, enforcing origin checks, and exchanging request/response messages without ad hoc `postMessage` glue.
+`@crup/port` exists for the part of embedded app work that usually rots first: lifecycle, handshake timing, and message discipline. It gives the host page a small runtime for mounting an iframe, opening it inline or in a modal, pinning exact origins, and exchanging request/response/error messages without ad hoc `postMessage` glue.
 
 Package: https://www.npmjs.com/package/@crup/port
 
@@ -85,6 +86,11 @@ const child = createChildPort({
 child.on('request:system:ping', (message) => {
   const request = message as { messageId: string; payload?: unknown };
 
+  if (!request.payload) {
+    child.reject(request.messageId, 'missing ping payload');
+    return;
+  }
+
   child.respond(request.messageId, {
     ok: true,
     receivedAt: Date.now()
@@ -98,11 +104,11 @@ child.resize(document.body.scrollHeight);
 ## What You Get
 
 - Explicit lifecycle: `idle -> mounting -> mounted -> handshaking -> ready -> open -> closed -> destroyed`
-- Strict origin pinning on both host and child
+- Explicit origin pinning on both host and child
 - Inline and modal host modes
-- Event emission plus request/response RPC
+- Event emission plus request/response/error RPC
 - Child-driven height updates
-- Small ESM-first bundle built with `tsup`
+- Small ESM-only bundle built with `tsup`
 
 ## API Surface
 
@@ -121,14 +127,15 @@ Host runtime with:
 - `update(partialConfig)`
 - `getState()`
 
-### `createChildPort(config?)`
+### `createChildPort(config)`
 
 Child runtime with:
 
 - `ready()`
 - `emit(type, payload?)`
 - `on(type, handler)`
 - `respond(messageId, payload)`
+- `reject(messageId, payload?)`
 - `resize(height)`
 - `destroy()`
 
@@ -167,6 +174,17 @@ type PortMessage = {
 - Release process: [`docs/releasing.md`](docs/releasing.md)
 - Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
 
+## Positioning
+
+`@crup/port` stays intentionally narrow:
+
+- it is a protocol runtime for iframe lifecycle, handshake, resize, and correlated messaging
+- it is not a framework adapter layer for React, Vue, or Web Components
+- it is not a generic method bridge that reaches into arbitrary child code
+- it is not an automatic DOM sync system beyond explicit child-driven `resize()`
+
+That scope is what keeps the package small and predictable.
+
 ## Local Development
 
 ```bash
@@ -189,12 +207,12 @@ Useful scripts:
 
 - `ci.yml` validates lint, types, tests, package build, demo build, README checks, size output, and package packing.
 - `docs.yml` deploys the Vite demo to GitHub Pages at `https://crup.github.io/port/`.
-- `release.yml` is a guarded manual stable release workflow modeled on `crup/react-timer-hook`.
+- `release.yml` is a guarded manual stable release workflow modeled on `crup/react-timer-hook`, and it persists the published version back to `main`.
 - `prerelease.yml` publishes a manual alpha prerelease from the `next` branch.
 
 ## Security
 
-This package helps with origin checks, but it cannot secure a weak embed strategy on its own. Always pin `allowedOrigin`, set restrictive iframe attributes, and validate application-level payloads. The practical guidance lives in [`docs/security.md`](docs/security.md).
+This package helps enforce the runtime boundary, but it cannot secure a weak embed strategy on its own. Always pin `allowedOrigin`, set restrictive iframe attributes, and validate application-level payloads. The practical guidance lives in [`docs/security.md`](docs/security.md).
 
 ## OSS Baseline
 

demo/index.html

@@ -41,8 +41,8 @@
             <p class="eyebrow">Protocol-first iframe runtime</p>
             <h1>Design the contract. Stop hand-wiring the window boundary.</h1>
             <p class="lede">
-              `@crup/port` gives embedded apps a real boundary: explicit handshake, strict origin checks,
-              child-driven resize, event routing, and request-response semantics that stay readable under
+              `@crup/port` gives embedded apps a real boundary: explicit handshake, exact origin pinning,
+              child-driven resize, event routing, and request-response-error semantics that stay readable under
               production pressure.
             </p>
             <div class="hero-actions">
@@ -101,15 +101,15 @@ <h1>Design the contract. Stop hand-wiring the window boundary.</h1>
             <div class="hero-principles">
               <div>
                 <strong>Handshake before traffic</strong>
-                <p>The child stays quiet until `port:hello` and origin validation succeed.</p>
+                <p>The child stays quiet until `port:hello` arrives from the configured exact origin.</p>
               </div>
               <div>
                 <strong>Events for telemetry</strong>
                 <p>Use `emit` and `send` for non-blocking UI and workflow signals.</p>
               </div>
               <div>
                 <strong>RPC for decisions</strong>
-                <p>Use `call` and `respond` when the host needs a concrete answer.</p>
+                <p>Use `call`, `respond`, and `reject` when the host needs a concrete answer or a real failure.</p>
               </div>
             </div>
           </div>
@@ -281,7 +281,7 @@ <h3>Modal Surface</h3>
             </article>
             <article>
               <h3>Child Responder</h3>
-              <p>Handle `request:*` messages and reply with `respond(messageId, payload)` to avoid ad hoc reply channels.</p>
+              <p>Handle `request:*` messages with `respond(messageId, payload)` or `reject(messageId, payload)` instead of ad hoc reply channels.</p>
               <a href="https://github.com/crup/port/blob/main/examples/child-basic.ts">Open example</a>
             </article>
             <article>

docs/api-reference.md

@@ -62,6 +62,8 @@ Removes a previously registered handler.
 
 Mutates the in-memory config for future runtime behavior.
 
+Once the port has mounted, only timeout and sizing fields may change. `url`, `allowedOrigin`, `target`, and `mode` are fixed for the lifetime of the mounted session.
+
 #### `getState(): PortState`
 
 Returns the current runtime state.
@@ -85,15 +87,15 @@ Returns the current runtime state.
 import { createChildPort } from '@crup/port/child';
 ```
 
-### `createChildPort(config?)`
+### `createChildPort(config)`
 
 Creates the child-side runtime that listens for the host handshake and communicates back to the parent window.
 
 #### Config
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
-| `allowedOrigin` | `string` | No | Explicit parent origin. If omitted, the child adopts the origin from the first valid `port:hello`. |
+| `allowedOrigin` | `string` | Yes | Exact parent origin accepted for the handshake and all later messages. |
 
 ### Methods
 
@@ -113,6 +115,10 @@ Subscribes to host traffic. Requests are surfaced as `request:<type>`.
 
 Resolves a previous host request.
 
+#### `reject(messageId: string, payload?: unknown): void`
+
+Rejects a previous host request. The host receives a `PortError` with code `MESSAGE_REJECTED`.
+
 #### `resize(height: number): void`
 
 Sends `event / port:resize` if the height is finite and non-negative.
@@ -130,7 +136,7 @@ Removes the child-side message listener.
 | `IFRAME_LOAD_TIMEOUT` | The iframe never produced `load()` within the allowed time. |
 | `HANDSHAKE_TIMEOUT` | The child never responded with `port:ready`. |
 | `CALL_TIMEOUT` | A request did not resolve before `callTimeoutMs`. |
-| `ORIGIN_MISMATCH` | Reserved for origin failures in application-level handling. |
+| `ORIGIN_MISMATCH` | Reserved for application-level contract handling when your own code detects an origin mismatch case. |
 | `MESSAGE_REJECTED` | The child replied with `kind: 'error'`. |
 | `PORT_DESTROYED` | The port was destroyed while work was in flight. |
 

docs/events-and-rpc.md

@@ -22,7 +22,7 @@ Avoid vague names like:
 ## Rule Of Thumb
 
 - `send()` / `emit()` for fire-and-forget signals
-- `call()` / `respond()` for data the host is blocked on
+- `call()` / `respond()` / `reject()` for data the host is blocked on
 
 ## Host To Child Events
 
@@ -109,6 +109,11 @@ Child:
 child.on('request:demo:getQuote', (message) => {
   const request = message as { messageId: string };
 
+  if (!quoteEngineReady()) {
+    child.reject(request.messageId, 'Quote engine unavailable');
+    return;
+  }
+
   child.respond(request.messageId, {
     plan: 'Growth',
     price: 249,
@@ -147,12 +152,10 @@ Document your own contract in a table like this:
 
 ## Error Strategy
 
-You have two choices when child-side work fails:
-
-1. respond with a domain payload that includes failure details
-2. emit `kind: 'error'` so the host receives `MESSAGE_REJECTED`
+You have two good choices when child-side work fails:
 
-The current child runtime exposes `respond()` only, so if you need richer rejection semantics you can either send a failure-shaped success payload or extend the runtime for explicit error responses.
+1. `reject(messageId, payload)` when the host should take a true failure path
+2. `respond(messageId, payload)` with a domain-level failure shape when the host still treats it as a normal result
 
 ## Good Contract Habits
 

docs/examples.md

@@ -6,7 +6,7 @@ These examples stay intentionally small, but they map directly to the runtime AP
 
 - `examples/host-inline.ts`: mount an iframe inline and subscribe to child events
 - `examples/host-modal.ts`: mount a modal port and control open and close explicitly
-- `examples/child-basic.ts`: respond to host requests and emit resize signals
+- `examples/child-basic.ts`: respond to host requests, reject invalid requests, and emit resize signals
 
 ## Live Demo
 
@@ -40,3 +40,15 @@ export function sendHostContext(port: Port, payload: HostContext) {
 ```
 
 This keeps the rest of the application from repeating message names everywhere.
+
+On the child side, do the same for both success and failure paths:
+
+```ts
+export function replyWithQuote(child: ChildPort, messageId: string, quote: QuoteResponse) {
+  child.respond(messageId, quote);
+}
+
+export function rejectQuote(child: ChildPort, messageId: string, reason: string) {
+  child.reject(messageId, { reason });
+}
+```

docs/getting-started.md

@@ -54,7 +54,7 @@ const child = createChildPort({
 });
 ```
 
-The child stays idle until it receives a valid `port:hello` message. Once origin validation succeeds, it replies with `port:ready` automatically.
+The child stays idle until it receives a valid `port:hello` message from the exact configured `allowedOrigin`. Once origin validation succeeds, it replies with `port:ready` automatically.
 
 ## First Working Flow
 
@@ -100,6 +100,11 @@ const quote = await port.call<{
 child.on('request:demo:getQuote', (message) => {
   const request = message as { messageId: string };
 
+  if (!document.body.dataset.quoteReady) {
+    child.reject(request.messageId, 'Quote engine is not ready yet');
+    return;
+  }
+
   child.respond(request.messageId, {
     plan: 'Growth',
     price: 249,
@@ -165,15 +170,18 @@ Destroying the port:
 
 - removes the iframe
 - clears pending RPC requests
+- clears pending handshake state
 - rejects outstanding calls with `PORT_DESTROYED`
 - removes message listeners
 
 ## Production Checklist
 
 - Pin `allowedOrigin` to the exact expected origin.
+- Treat `createChildPort({ allowedOrigin })` as required security config, not optional convenience.
 - Keep runtime messages generic and put business rules in your own named events and requests.
 - Document event names, payloads, and ownership between host and child teams.
 - Use `call()` only when the host truly depends on the child response.
+- Use `reject()` when the child cannot satisfy a host request and the host should handle a real failure path.
 - Add runtime logging around `mount`, handshake, request start, request completion, and destroy.
 - Add browser tests for the actual iframe flows your product depends on.
 

docs/lifecycle.md

@@ -125,6 +125,8 @@ Look at:
 - `allowedOrigin` mismatch
 - `handshakeTimeoutMs` too low for the actual child startup path
 
+Failed `mount()` calls now clean up the iframe and reset the runtime to `idle`, so a corrected retry can mount again without creating a poisoned instance.
+
 ### Host calls too early
 
 `send()` and `call()` require the runtime to be `ready`, `open`, or `closed`. Calling them earlier throws `INVALID_STATE`.

docs/protocol.md

@@ -22,7 +22,7 @@ type PortMessage = {
 - Messages are ignored unless `protocol` and `version` match.
 - The host accepts messages only from the currently mounted iframe window.
 - The host ignores messages from any origin other than `allowedOrigin`.
-- The child ignores messages until it has observed a valid `port:hello`.
+- The child ignores messages until it has observed a valid `port:hello` from the configured `allowedOrigin`.
 - `instanceId` prevents sibling embeds from handling each other’s traffic.
 - `replyTo` ties responses and errors to a single outstanding request.
 
@@ -89,7 +89,12 @@ Child:
 
 ```ts
 child.on('request:demo:getQuote', (message) => {
-  const request = message as { messageId: string };
+ const request = message as { messageId: string };
+
+  if (!quoteEngineReady()) {
+    child.reject(request.messageId, 'Quote engine unavailable');
+    return;
+  }
 
   child.respond(request.messageId, {
     plan: 'Growth',

docs/releasing.md

@@ -14,7 +14,7 @@ This repository now has a release flow similar in shape to `crup/react-timer-hoo
 - `release.yml` is a manual workflow dispatch from `main`.
 - It uses a guarded release gate, a separate verify job, and a dedicated publish job.
 - `NPM_TOKEN` is passed directly to the publish step via `NODE_AUTH_TOKEN` and `NPM_TOKEN`.
-- After publish, the workflow creates a GitHub release tag and release notes.
+- After publish, the workflow commits the released `package.json` version back to `main`, then creates the GitHub release tag and notes from that release commit.
 
 Required secrets: