Clarify architecture boundaries and public API

.github/workflows/ci.yml

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [main]
 
+# A PR can receive many small stabilization commits. Only the newest SHA is
+# useful; cancel stale runs so they do not consume the cross-platform runners
+# or delay feedback for the current head.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}
@@ -27,12 +34,41 @@ jobs:
         shell: bash
         run: raco pkg install --auto --no-docs --link "$PWD"
 
+      - name: Compile public entrypoints
+        run: raco make glaze/main.rkt glaze-cli/cli.rkt scripts/package-entry-smoke.rkt
+
       - name: Run tests
         run: raco test glaze-test/
 
-      - name: Check formatting
-        run: raco fmt --check glaze/ glaze-cli/ glaze-test/
-        continue-on-error: true
+  source-package:
+    # Release hygiene: prove the filtered source archive is independently
+    # installable. This job intentionally does not link the checkout first.
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Racket
+        uses: Bogdanp/setup-racket@v1.11
+        with:
+          version: '8.12'
+
+      - name: Create source package
+        shell: bash
+        run: |
+          cd ..
+          raco pkg create --source --format zip glaze
+          test -s glaze.zip
+
+      - name: Install source package archive
+        shell: bash
+        run: raco pkg install --auto --no-docs ../glaze.zip
+
+      - name: Verify installed facade and CLI
+        shell: bash
+        run: |
+          racket -e '(require glaze) (unless (procedure? run-app) (error "missing run-app"))'
+          raco glaze help
 
   webview-e2e:
     # Real-window WebView end-to-end on each OS: open -> load (title
@@ -112,20 +148,31 @@ jobs:
 
       - name: Install installer toolchain (Windows)
         if: runner.os == 'Windows'
+        shell: pwsh
         run: |
-          # WiX Toolset v4 (build falls back to zip if missing)
-          dotnet tool install --global wix
-          echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
+          # Glaze supports WiX v4 syntax, but GitHub's latest global `wix`
+          # tool is now v7 and requires an additional OSMF license flow.
+          # NSIS is the other supported native Windows installer backend.
+          choco install nsis -y --no-progress
+          $nsis = "C:\Program Files (x86)\NSIS"
+          if (Test-Path $nsis) { $nsis | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append }
+
+      - name: Verify packaged entry executes
+        run: racket scripts/package-entry-smoke.rkt
 
       - name: Scaffold and build a sample app
         shell: bash
         run: |
           raco glaze init sampleapp
           cd sampleapp
-          # --sign - exercises the signing pipeline everywhere: macOS signs
-          # the bundle ad-hoc (verifiable without a cert); Windows/Linux
-          # degrade with a loud warning when no signing toolchain exists.
-          raco glaze build --name sampleapp --version 0.0.1 --out dist --installer --sign -
+          # Exercise signing where CI can do it without secrets. On macOS,
+          # ad-hoc signing is verifiable; Windows signing correctly requires a
+          # real certificate and is covered by argument/tool failure behavior.
+          if [ "$RUNNER_OS" = "macOS" ]; then
+            raco glaze build --name sampleapp --version 0.0.1 --out dist --installer --sign -
+          else
+            raco glaze build --name sampleapp --version 0.0.1 --out dist --installer
+          fi
       - name: Verify macOS bundle signature
         if: runner.os == 'macOS'
         run: |
@@ -143,3 +190,24 @@ jobs:
             sampleapp/dist/*.msi
             sampleapp/dist/*.dmg
             sampleapp/dist/*.AppImage
+
+  package-racket-9-3-macos:
+    # Regression coverage for the macOS/Racket 9.3 launcher failure reported
+    # in issue #1. This job executes the final packaged binary, not merely the
+    # build command.
+    runs-on: macOS-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Racket
+        uses: Bogdanp/setup-racket@v1.11
+        with:
+          version: '9.3'
+
+      - name: Install Glaze package
+        shell: bash
+        run: raco pkg install --auto --no-docs --link "$PWD"
+
+      - name: Verify packaged entry executes
+        run: racket scripts/package-entry-smoke.rkt

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+- `run-app` now enables a random API capability token by default; pass
+  `#:api-token #f` explicitly for an intentionally open local API.
+- Update checks are non-blocking from the application lifecycle and enforce a
+  five-second fetch timeout, 2xx status, and a 1 MiB manifest limit.
+- `raco glaze init` scaffolds the recommended `run-app` / `(require glaze)`
+  entry and refuses to overwrite non-empty project directories.
+
+### Fixed
+- Packaging now compiles the user's real entry module, preserving
+  `(module+ main ...)` execution instead of producing launchers that could
+  exit successfully without running the application.
+- Static-file serving rejects traversal outside `public/`, including resolved
+  symlinks, and Host validation correctly handles bracketed IPv6 loopback.
+- API handler exceptions are reported to the trusted error callback but no
+  longer leak arbitrary exception text in 500 responses.
+- Generated JavaScript API bindings safely escape route segments and no longer
+  use route parameter text as raw JavaScript identifiers.
+- Shutdown is idempotent, single-instance listeners are retained for process
+  lifetime with deterministic cross-process ports, and tray operations dispatch
+  from each tray handle rather than process-global fallback state.
+
+
 ## [0.6.0] - 2026-09-15
 
 ### Added

CONTRIBUTING.md

@@ -1,48 +1,75 @@
 # Contributing to Glaze
 
+Glaze is a pre-1.0 cross-platform desktop framework. Prefer small changes that preserve application-facing APIs and keep platform details behind the public dispatchers.
+
 ## Development Setup
 
 ```bash
 git clone https://github.com/turinglambdaai/glaze.git
 cd glaze
-raco pkg install --auto --link "$PWD"
+raco pkg install --auto --no-docs --link "$PWD"
 ```
 
-(The repo root is one single Racket package — this installs the library,
-the `raco glaze` CLI, and the docs in one step. `"$PWD"` is needed because
-`raco pkg install` requires the source path to end in the package name.
-After pulling changes, refresh with `raco pkg update --link "$PWD"`.)
+The repository root is one installable Racket package using `collection 'multi`; the `glaze`, `glaze-cli`, `glaze-doc`, and `glaze-test` collections are installed together.
+
+## Before Opening a Pull Request
 
-## Running Tests
+Run the platform-independent suite and compile the public entrypoints:
 
 ```bash
+raco make glaze/main.rkt glaze-cli/cli.rkt scripts/package-entry-smoke.rkt
 raco test glaze-test/
 ```
 
+When your change touches WebView or packaging behavior, also run the relevant verification script on the affected operating system. CI exercises native WebView behavior and package construction on Windows, macOS, and Linux, including a macOS/Racket 9.3 packaging regression test.
+
+## Architecture Rules
+
+Read [`docs/architecture.md`](docs/architecture.md) before moving modules or adding a new capability. In particular:
+
+- normal applications should prefer `(require glaze)`;
+- `glaze/main.rkt` is the compatibility-preserving application facade;
+- platform-specific modules belong behind `webview/main.rkt`, `tray/main.rkt`, or `sys/main.rkt`;
+- do not make platform backends depend on application-level orchestration;
+- shared protocols should not be duplicated independently in each backend;
+- avoid large directory migrations solely for aesthetics;
+- new public behavior should have a platform-independent contract test when possible.
+
 ## Code Style
 
-- Follow standard Racket conventions
-- Use `raco fmt` for formatting
-- Add tests for new features
-- Update Scribble documentation
+Follow the dominant Racket style already present in the repository. The optional [`fmt`](https://pkgs.racket-lang.org/package/fmt) package can be installed with:
+
+```bash
+raco pkg install fmt
+```
+
+Do not reformat unrelated files in a functional pull request. Formatting-only churn makes native and lifecycle changes harder to review.
+
+## Tests and Documentation
+
+A change is not complete when only the happy path works. Prefer small regression tests for:
+
+- public facade exports and argument validation;
+- lifecycle and cleanup behavior;
+- platform-independent protocol logic;
+- security boundaries such as path containment and localhost API access;
+- package artifacts that actually execute, not merely build successfully.
+
+Update Scribble/API documentation and user-facing examples when a public contract changes. Do not document features that are only planned.
 
 ## Pull Requests
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run tests
-5. Submit a PR with a clear description
+Keep each PR focused enough to explain why every changed file is necessary. In the description include the problem, compatibility impact, tests run, and any platform behavior you could not verify locally.
 
-## Package Structure
+Security issues should follow [`SECURITY.md`](SECURITY.md) instead of being disclosed with exploit details in a public issue.
 
-The repo root is a single installable package; each top-level directory is a
-Racket collection:
+## Package Structure
 
 | Directory | Purpose |
-|-----------|---------|
-| `glaze/` | Core implementation (collection `glaze`) |
+|---|---|
+| `glaze/` | Framework implementation and public facade |
 | `glaze-cli/` | `raco glaze` commands |
 | `glaze-doc/` | Scribble documentation |
-| `glaze-test/` | Tests |
-| `examples/` | Runnable examples (not compiled by setup) |
+| `glaze-test/` | Regression and contract tests |
+| `examples/` | Runnable examples |
+| `scripts/` | CI and verification scripts |