docs: add a published-package sandbox for the chat room example

[electrohyun]

Context

examples/chat-room is the application example maintained in this repository. It consumes smocket through workspace:*, so pnpm example:chat-room builds and exercises the source under review.

That role should remain intact while #113 establishes the chat room application scenario.

Problem

The workspace-backed example does not reproduce how an independent application consumes Smocket.

A real consumer starts outside the Smocket workspace, installs the package through a package boundary, and runs with its own manifest, lockfile, dependencies, and test setup. The current example therefore does not verify:

• that a clean consumer can install the package published to npm;
• that the published package works outside Smocket's workspace and development dependencies;
• that the package produced by a pull request works when installed as an artifact;
• that the maintained application workflow remains usable from an independent project;
• that a reader can open and run the example without cloning the full Smocket repository.

The existing package checks validate the published manifest, imports, types, and built output. The dual-run suite remains the source of truth for declared Socket.IO behavior. Neither check replaces an independent consumer exercising the package as an application dependency.

Scope

Create an independent consumer based on the application scenario established by #113.

The consumer must support two package inputs:

1. Published-package validation: install a released smocket version from npm and run the maintained application test.
2. Candidate-package validation: pack the Smocket source under review, install the resulting tarball into the consumer, and run the same test before the change is released.

The consumer's committed configuration must not depend on workspace:* or Smocket's local source. Candidate-package validation may temporarily replace the released dependency with the packed tarball during CI.

Provide a repository-backed browser sandbox for the consumer where the selected sandbox can support its runtime and installation requirements. The sandbox is an entry point to the maintained consumer, not a separate mutable copy owned by a personal sandbox account.

Repository decision

Decide whether the independent consumer belongs:

• in this repository as an isolated consumer fixture;
• in a dedicated public repository such as smocket-lab; or
• in another repository-backed structure that provides the same independent package boundary.

Make this decision after #113 establishes the strengthened application scenario and its test shape. The decision does not block strengthening examples/chat-room in the main repository.

Evaluate the options by:

• whether installation is genuinely isolated from the Smocket workspace;
• how reliably Smocket CI can inject and test a candidate tarball;
• how the consumer selects and updates its published Smocket version;
• how a trusted consumer commit or ref is selected if another repository is used;
• how much duplicated code and synchronization the structure introduces;
• how dependency and framework updates are maintained;
• how easily a reader can open and run the consumer;
• how much recurring CI and repository maintenance the structure requires.

Record the selected structure and the reasons for rejecting the other viable options.

Validation boundaries

The independent consumer complements the existing checks rather than replacing them.

• examples/chat-room continues to exercise the source under review through workspace:*.
• The dual-run conformance suite remains the source of truth for observable compatibility with Socket.IO.
• The independent consumer verifies packaging, installation, setup, integration, and the maintained application workflow across the consumer boundary.
• The consumer must not duplicate the core conformance suite method by method.
• If the application reveals an unverified or mismatched Socket.IO behavior, measure it against real Socket.IO and add it to the dual-run conformance suite before treating it as a compatibility guarantee.
• If a separate repository is selected, Smocket behavior reports remain in the main repository. The external repository tracks only problems with its own application, dependencies, sandbox, or validation harness.

#218 may reuse evidence produced by this consumer, but application reporting and productivity comparison are outside this issue and do not determine its design or completion.

Published-version policy

Before implementation is complete, decide and document:

• which released Smocket version the committed consumer installs;
• whether its manifest declares an exact version or a compatible range;
• how the lockfile affects the version actually exercised by CI;
• when and how the published version is updated;
• which events run published-package validation;
• which events run candidate-package validation.

The published-package and candidate-package modes answer different questions and may use different version inputs. A compatible manifest range alone does not prove that CI has exercised every compatible release.

Completion

• The repository location of the independent consumer is decided and documented.
• The consumer is reproducible from repository content.
• A clean install resolves smocket from npm without workspace:*, a local source path, or Smocket's existing node_modules.
• Published-package validation runs the application scenario established by docs: expand the chat room into an application workflow #113 and verifies its deterministic expected results.
• Candidate-package validation packs the source under review, installs the resulting tarball into the consumer, and runs the same application test.
• Candidate-package validation is connected to Smocket's pull request CI.
• The existing workspace-backed examples/chat-room remains in Smocket CI.
• A clean browser session can open the repository-backed sandbox without cloning the full Smocket repository.
• The sandbox uses the published Smocket package and runs on Node.js 20 or later.
• The root README and examples/chat-room/README.md link to the maintained consumer or sandbox.
• The package-input and update policies are documented.
• The validation documentation distinguishes the independent consumer from the dual-run conformance guarantee.
• pnpm format:check passes for changes made in this repository.

Related: #113, #213, #218.

[electrohyun]

For decision context, MSW's public examples repository and downstream smoke-test script were reviewed as one existing implementation of separate consumer validation:

• https://github.com/mswjs/examples
• https://github.com/mswjs/msw/blob/main/config/scripts/smoke-test.sh

This is evidence that the arrangement is technically viable, not a decision to adopt it. Smocket's repository boundary will be chosen from its own CI gaps and maintenance constraints.