npm - create-prisma-php-app - Versions diffs - 5.0.0-alpha.8 → 5.0.0 - Mend

create-prisma-php-app 5.0.0-alpha.8 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/README.md +23 -2
package/dist/.github/copilot-instructions.md +191 -0
package/dist/AGENTS.md +588 -193
package/dist/bootstrap.php +426 -213
package/dist/index.js +2 -2
package/dist/phpunit.xml +25 -0
package/dist/postcss.config.js +4 -2
package/dist/prisma-php.js +2 -2
package/dist/public/.htaccess +1 -1
package/dist/public/js/main.js +13 -1
package/dist/public/js/pp-reactive-v2.min.js +1 -0
package/dist/settings/auto-swagger-docs.ts +10 -10
package/dist/settings/bs-config.ts +47 -27
package/dist/settings/build.ts +2 -32
package/dist/settings/component-map.ts +476 -0
package/dist/settings/files-list.ts +2 -2
package/dist/settings/project-name.ts +3 -6
package/dist/settings/restart-mcp.ts +2 -2
package/dist/settings/restart-websocket.ts +2 -2
package/dist/settings/run-postcss.ts +205 -0
package/dist/settings/run-tests.ts +35 -0
package/dist/settings/swagger-config.ts +3 -3
package/dist/settings/utils.ts +3 -3
package/dist/src/Lib/Auth/Auth.php +62 -34
package/dist/src/Lib/MCP/mcp-server.php +2 -3
package/dist/src/Lib/Middleware/CorsMiddleware.php +72 -0
package/dist/src/Lib/Websocket/ConnectionManager.php +460 -7
package/dist/src/Lib/Websocket/Socket.php +170 -0
package/dist/src/Lib/Websocket/SocketPool.php +50 -0
package/dist/src/Lib/Websocket/SocketRegistry.php +88 -0
package/dist/src/Lib/Websocket/sockets.php +50 -0
package/dist/src/Lib/Websocket/websocket-server.php +10 -3
package/dist/src/app/globals.css +3 -1
package/dist/src/app/layout.php +1 -1
package/dist/tests/AuthTest.php +59 -0
package/dist/tests/ConnectionManagerTest.php +277 -0
package/dist/tests/CsrfTest.php +119 -0
package/dist/tests/DeferComponentRootsTest.php +147 -0
package/dist/tests/FeaturesTest.php +41 -0
package/dist/tests/README.md +119 -0
package/dist/tests/RpcWireContractTest.php +101 -0
package/dist/tests/SocketPoolTest.php +69 -0
package/dist/tests/SocketRegistryTest.php +77 -0
package/dist/tests/SocketTest.php +124 -0
package/dist/tests/SocketsRegistrationTest.php +40 -0
package/dist/tests/Support/FakeConnection.php +62 -0
package/dist/tests/Support/Features.php +38 -0
package/dist/tests/Support/RequiresFeature.php +26 -0
package/dist/tests/bootstrap.php +44 -0
package/dist/ts/main.ts +21 -3
package/dist/ts/tailwind-merge.ts +13 -0
package/package.json +4 -4
package/dist/README.md +0 -213
package/dist/public/js/pp-reactive-v2.js +0 -1
package/dist/settings/bs-config.json +0 -6
package/dist/settings/class-imports.ts +0 -165
package/dist/settings/class-log.ts +0 -244
package/dist/settings/component-import-checker.ts +0 -90
package/dist/settings/files-list.json +0 -1
package/dist/settings/prisma-schema-config.json +0 -16

package/dist/tests/DeferComponentRootsTest.php ADDED Viewed

@@ -0,0 +1,147 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use PHPUnit\Framework\TestCase;
+use PP\PHPX\TemplateCompiler;
+/**
+ * The server-deferred component-root contract, as the app depends on it.
+ *
+ * The final document wraps every outermost `[pp-component]` root inside
+ * `<body>` in an inert `<template pp-component="...">`. The browser never
+ * executes scripts or parses `{...}` placeholders inside a template, so
+ * component scripts cannot run before the PulsePoint runtime module loads
+ * ("pp is not defined") and raw placeholders cannot trigger bogus requests
+ * or value coercion before hydration. `pp.mount()` materializes
+ * `template[pp-component]` back into live DOM before scanning for roots.
+ */
+final class DeferComponentRootsTest extends TestCase
+{
+    private function document(string $bodyContent): string
+    {
+        return "<html>\n<head><title>t</title></head>\n<body>\n"
+            . $bodyContent
+            . "\n</body>\n</html>";
+    }
+    public function testWrapsRouteRootInInertTemplate(): void
+    {
+        $html = $this->document(
+            '<div pp-component="page_abc123">'
+            . '<p>Count: {count}</p>'
+            . '<script>const [count, setCount] = pp.state(0);</script>'
+            . '</div>'
+        );
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertStringContainsString(
+            '<template pp-component="page_abc123"><div pp-component="page_abc123">',
+            $deferred
+        );
+        self::assertStringContainsString('</div></template>', $deferred);
+        // The component script rides along inside the inert template, unchanged.
+        self::assertStringContainsString(
+            '<script>const [count, setCount] = pp.state(0);</script>',
+            $deferred
+        );
+    }
+    public function testOnlyOutermostBoundaryIsWrapped(): void
+    {
+        $html = $this->document(
+            '<div pp-component="layout_1">'
+            . '<div pp-component="page_2"><p>{msg}</p></div>'
+            . '</div>'
+        );
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertSame(1, substr_count($deferred, '<template pp-component='));
+        self::assertStringContainsString('<template pp-component="layout_1">', $deferred);
+        // The nested boundary stays a plain element inside the inert content.
+        self::assertStringContainsString('<div pp-component="page_2">', $deferred);
+    }
+    public function testWrapsFooterComponentScript(): void
+    {
+        $html = $this->document(
+            '<div pp-component="page_1"><p>hi</p></div>'
+            . '<script pp-component="s9footer">pp.state(1);</script>'
+        );
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertStringContainsString(
+            '<template pp-component="s9footer"><script pp-component="s9footer">pp.state(1);</script></template>',
+            $deferred
+        );
+    }
+    public function testSiblingBoundariesAreEachWrapped(): void
+    {
+        $html = $this->document(
+            '<main><div pp-component="a"><span>x</span></div>'
+            . '<div pp-component="b"><span>y</span></div></main>'
+        );
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertStringContainsString('<template pp-component="a"><div pp-component="a">', $deferred);
+        self::assertStringContainsString('<template pp-component="b"><div pp-component="b">', $deferred);
+    }
+    public function testEscapedBraceEntitiesGainOneEncodingLayer(): void
+    {
+        // The browser's parse of the template content consumes one entity
+        // layer; the extra `&amp;` keeps the escape visible to the runtime.
+        $html = $this->document(
+            '<div pp-component="page_1"><code>&#123;literal&#125;</code>'
+            . '<script>const s = "&#123;";</script></div>'
+        );
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertStringContainsString('<code>&amp;#123;literal&amp;#125;</code>', $deferred);
+        // Script content is raw text in the template parse — left untouched.
+        self::assertStringContainsString('const s = "&#123;";', $deferred);
+    }
+    public function testHeadContentIsNeverWrapped(): void
+    {
+        $html = "<html>\n<head><meta name=\"x\" pp-component=\"nope\"></head>\n<body>\n"
+            . '<div pp-component="page_1"><p>hi</p></div>'
+            . "\n</body>\n</html>";
+        $deferred = TemplateCompiler::deferComponentRoots($html);
+        self::assertStringNotContainsString('<template pp-component="nope">', $deferred);
+        self::assertStringContainsString('<template pp-component="page_1">', $deferred);
+    }
+    public function testAlreadyDeferredTemplateIsLeftAlone(): void
+    {
+        $html = $this->document(
+            '<template pp-component="page_1"><div pp-component="page_1"><p>hi</p></div></template>'
+        );
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+    public function testDocumentWithoutBoundariesIsUnchanged(): void
+    {
+        $html = $this->document('<div><p>plain</p></div>');
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+    public function testUnbalancedBoundaryMarkupLeavesDocumentUntouched(): void
+    {
+        $html = $this->document('<div pp-component="page_1"><p>never closed');
+        self::assertSame($html, TemplateCompiler::deferComponentRoots($html));
+    }
+}

package/dist/tests/FeaturesTest.php ADDED Viewed

@@ -0,0 +1,41 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\Features;
+/**
+ * The suite's own feature awareness: flags come from `prisma-php.json`, the
+ * single source of truth for which optional scaffolds exist in this app.
+ */
+final class FeaturesTest extends TestCase
+{
+    public function testConfigIsReadFromPrismaPhpJson(): void
+    {
+        $raw = json_decode((string) file_get_contents(DOCUMENT_PATH . '/prisma-php.json'), true);
+        self::assertIsArray($raw);
+        self::assertSame($raw, Features::config());
+    }
+    public function testEnabledMirrorsTheBooleanFlags(): void
+    {
+        $config = Features::config();
+        foreach (['websocket', 'mcp', 'swaggerDocs', 'prisma', 'tailwindcss', 'typescript'] as $flag) {
+            self::assertSame(
+                ($config[$flag] ?? false) === true,
+                Features::enabled($flag),
+                "Features::enabled('$flag') mirrors prisma-php.json"
+            );
+        }
+    }
+    public function testAnUnknownFlagIsDisabled(): void
+    {
+        self::assertFalse(Features::enabled('not-a-real-feature'));
+    }
+}

package/dist/tests/README.md ADDED Viewed

@@ -0,0 +1,119 @@
+# App tests
+PHPUnit tests for the **application** code — `src/Lib/**`, the app's wire
+contracts, and `src/Lib/Websocket/sockets.php` registrations — not the Prisma
+PHP framework under `vendor/tsnc/prisma-php` (that package carries its own
+suite in its source repo).
+## The command
+```bash
+npm run test
+```
+That runs PHPUnit through `settings/run-tests.ts`, which uses the PHP binary
+from `prisma-php.json` (`phpRootPathExe`) so the suite runs with the same PHP
+the app runs on. It exits non-zero on any failure, so CI, a pre-commit hook,
+or an agent knows exactly when something broke.
+Narrow a run with PHPUnit's own flags after `--`:
+```bash
+npm run test -- --filter CsrfTest
+npm run test -- --filter testValidTokenRoundTrip
+```
+Running PHPUnit directly also works: `php vendor/phpunit/phpunit/phpunit`
+(configuration is picked up from `phpunit.xml` at the project root).
+## Layout
+One file per surface, flat in `tests/`:
+| File | Surface |
+| --- | --- |
+| `bootstrap.php` | Shared setup: autoloader, path constants, deterministic test env |
+| `Support/` | Reusable fakes (`Tests\Support\...`, autoloaded via composer `autoload-dev`) |
+| `Support/Features.php` | Feature flags read from `prisma-php.json` |
+| `Support/RequiresFeature.php` | Skip guard for tests of optional features |
+| `FeaturesTest.php` | The suite's own feature awareness mirrors `prisma-php.json` |
+| `CsrfTest.php` | The `pp_csrf` cookie family and `X-CSRF-Token` validation |
+| `RpcWireContractTest.php` | PulsePoint wire headers (`$isRpc` / `$isNavigation` / `$isWire`), including the pin that the legacy header stays dead |
+| `DeferComponentRootsTest.php` | Server-deferred component roots: outermost `[pp-component]` body roots ship inside inert `<template pp-component>` wrappers |
+| `SocketTest.php` | One socket connection: JSON frames, reserved error shape, close semantics |
+| `SocketRegistryTest.php` | Named-socket registration and duplicate refusal |
+| `SocketPoolTest.php` | Broadcast and pruning |
+| `ConnectionManagerTest.php` | The full named-socket wire: handshake refusals, argument frame, auth, limits |
+| `SocketsRegistrationTest.php` | The app's real `sockets.php` loads and names its sockets |
+| `AuthTest.php` | JWT round trip, tamper/expiry/foreign-secret rejection |
+## The test environment is deterministic
+`tests/bootstrap.php` does **not** load the real `.env`. It loads the composer
+autoloader plus `settings/paths.php`, then sets deterministic defaults
+(`APP_ENV=development`, a 32-byte `AUTH_SECRET`, `FUNCTION_CALL_SECRET`) only
+when the variable is not already set — so the suite behaves the same on any
+machine, never depends on real secrets, and CI can still override. The Prisma
+PHP `bootstrap.php` at the project root (route resolution, rendering, CSRF
+cookie issuing) is **not** booted; tests exercise app classes directly.
+A test that needs a different env value must set it with `putenv(...)` and
+restore the previous value in `tearDown()` (`PP\Env` reads `getenv()` first) —
+see `ConnectionManagerTest::setEnv()` for the pattern.
+## Optional features are optional in the suite too
+`prisma-php.json` decides which optional scaffolds exist (`websocket`, `mcp`,
+`swaggerDocs`, `prisma`, ...). A test for an optional feature must guard on
+the flag, or a freshly generated app without that feature fatals instead of
+passing:
+```php
+use Tests\Support\RequiresFeature;
+final class MySocketTest extends TestCase
+{
+    use RequiresFeature;
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket'); // FIRST line, before touching the scaffold
+    }
+}
+```
+When the flag is off the test reports itself as skipped with the reason and
+the enable command — never as a failure. `tearDown()` still runs after a
+skip, so teardown code must not assume the feature's classes exist (see
+`SocketRegistryTest::resetRegistry()` for the `class_exists` guard).
+The websocket suites (`SocketTest`, `SocketRegistryTest`, `SocketPoolTest`,
+`ConnectionManagerTest`, `SocketsRegistrationTest`) are gated this way. Core
+surfaces — CSRF, the RPC wire headers, auth — are always-on and never gated.
+## Conventions
+- one `SomethingTest.php` per surface, in the `Tests` namespace; shared fakes
+  live in `tests/Support` under `Tests\Support`
+- static registries (`SocketRegistry`) are reset in `setUp()`/`tearDown()` via
+  reflection so tests never depend on each other's order
+- superglobals a test touches (`$_SERVER`, `$_COOKIE`, env) are backed up in
+  `setUp()` and restored in `tearDown()`
+- wire tests assert **frames and close codes**, not internals:
+  `Tests\Support\FakeConnection` records everything the server sends, so a
+  test reads the conversation the browser would have seen
+- expected framework failures are part of the contract — a refusal test
+  asserts the readable `{"error": "..."}` frame (or HTTP status), not just
+  "something failed"
+- tests cover app-level code and the wire contracts the app depends on; do
+  not test Prisma PHP internals from here — those belong to the package
+  repo's own suite (`vendor/tsnc/prisma-php/tests` when vendored)
+## For AI agents
+Read this file plus `node_modules/prisma-php/dist/docs/testing.md` before
+adding or changing tests. When you add an app feature with logic worth
+protecting — an exposed function's validation, a socket handler, an auth
+rule — add the matching `*Test.php` here in the same change, and run
+`npm run test` before declaring the work done. A red suite is a finding to
+fix, not to silence.

package/dist/tests/RpcWireContractTest.php ADDED Viewed

@@ -0,0 +1,101 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use PHPUnit\Framework\TestCase;
+use PP\Request;
+/**
+ * The PulsePoint wire headers, as the app depends on them.
+ *
+ * `pp.rpc(...)` posts with `X-PP-RPC: true` + `X-PP-Function`; SPA navigation
+ * fetches with `X-PP-Navigation: true`; both carry `X-PulsePoint-Wire: true`.
+ * This is a complete migration — the legacy `PP-Wire-Request` header must NOT
+ * be recognized any more, and that is pinned here on purpose.
+ */
+final class RpcWireContractTest extends TestCase
+{
+    private array $serverBackup = [];
+    protected function setUp(): void
+    {
+        $this->serverBackup = $_SERVER;
+    }
+    protected function tearDown(): void
+    {
+        $_SERVER = $this->serverBackup;
+    }
+    private function initRequest(array $server): void
+    {
+        $_SERVER = array_merge([
+            'HTTP_HOST' => 'example.test',
+            'SCRIPT_NAME' => '/index.php',
+            'REMOTE_ADDR' => '127.0.0.1',
+        ], $server);
+        Request::init();
+    }
+    public function testRpcPostIsDetected(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_RPC' => 'true',
+            'HTTP_X_PP_FUNCTION' => 'saveProfile',
+        ]);
+        self::assertTrue(Request::$isWire);
+        self::assertTrue(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+    public function testNavigationGetIsWireButNotRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PULSEPOINT_WIRE' => 'true',
+            'HTTP_X_PP_NAVIGATION' => 'true',
+        ]);
+        self::assertTrue(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertTrue(Request::$isNavigation);
+    }
+    public function testRpcHeaderOnAGetIsNotAnRpc(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'GET',
+            'HTTP_X_PP_RPC' => 'true',
+        ]);
+        self::assertFalse(Request::$isRpc);
+    }
+    public function testPlainRequestCarriesNoWireFlags(): void
+    {
+        $this->initRequest(['REQUEST_METHOD' => 'GET']);
+        self::assertFalse(Request::$isWire);
+        self::assertFalse(Request::$isRpc);
+        self::assertFalse(Request::$isNavigation);
+    }
+    public function testLegacyWireHeaderIsNoLongerRecognized(): void
+    {
+        $this->initRequest([
+            'REQUEST_METHOD' => 'POST',
+            'CONTENT_TYPE' => 'application/json',
+            'HTTP_PP_WIRE_REQUEST' => 'true',
+        ]);
+        self::assertFalse(Request::$isWire, 'complete migration: no legacy header support');
+        self::assertFalse(Request::$isRpc);
+    }
+}

package/dist/tests/SocketPoolTest.php ADDED Viewed

@@ -0,0 +1,69 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use Lib\Websocket\Socket;
+use Lib\Websocket\SocketPool;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+/**
+ * A broadcast pool: one value to everyone, with gone connections pruned on
+ * the way.
+ */
+final class SocketPoolTest extends TestCase
+{
+    use RequiresFeature;
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+    }
+    public function testBroadcastReachesEveryOpenSocket(): void
+    {
+        $pool = new SocketPool();
+        $connA = new FakeConnection();
+        $connB = new FakeConnection();
+        $pool->add(new Socket($connA, 'chat'));
+        $pool->add(new Socket($connB, 'chat'));
+        $pool->broadcast(['text' => 'hello room']);
+        self::assertSame([['text' => 'hello room']], $connA->sentFrames);
+        self::assertSame([['text' => 'hello room']], $connB->sentFrames);
+    }
+    public function testClosedSocketsArePrunedByBroadcast(): void
+    {
+        $pool = new SocketPool();
+        $connA = new FakeConnection();
+        $gone = new Socket(new FakeConnection(), 'chat');
+        $pool->add(new Socket($connA, 'chat'));
+        $pool->add($gone);
+        $gone->handleClose();
+        $pool->broadcast('first');
+        self::assertSame(1, $pool->count(), 'the closed connection was forgotten');
+        self::assertSame(['first'], $connA->sentFrames);
+    }
+    public function testDiscardRemovesOnlyThatSocket(): void
+    {
+        $pool = new SocketPool();
+        $keep = new Socket(new FakeConnection(), 'chat');
+        $drop = new Socket(new FakeConnection(), 'chat');
+        $pool->add($keep);
+        $pool->add($drop);
+        $pool->discard($drop);
+        self::assertSame(1, $pool->count());
+    }
+}

package/dist/tests/SocketRegistryTest.php ADDED Viewed

@@ -0,0 +1,77 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use InvalidArgumentException;
+use Lib\Websocket\SocketRegistry;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use Tests\Support\RequiresFeature;
+/**
+ * The named-socket registry: names are the whole address, so they are unique
+ * application-wide and a duplicate is refused at registration time.
+ */
+final class SocketRegistryTest extends TestCase
+{
+    use RequiresFeature;
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+        self::resetRegistry();
+    }
+    protected function tearDown(): void
+    {
+        self::resetRegistry();
+    }
+    public static function resetRegistry(): void
+    {
+        // tearDown() still runs after a feature skip, and in an app without
+        // the websocket scaffold the class does not exist — nothing to reset.
+        if (!class_exists(SocketRegistry::class)) {
+            return;
+        }
+        $reflection = new ReflectionClass(SocketRegistry::class);
+        $reflection->getProperty('sockets')->setValue(null, []);
+    }
+    public function testRegisterAndResolveByName(): void
+    {
+        $handler = static function (): void {};
+        SocketRegistry::register('chat', $handler, requireAuth: true, allowedRoles: ['admin']);
+        $entry = SocketRegistry::get('chat');
+        self::assertNotNull($entry);
+        self::assertSame('chat', $entry['name']);
+        self::assertSame($handler, $entry['handler']);
+        self::assertTrue($entry['requireAuth']);
+        self::assertSame(['admin'], $entry['allowedRoles']);
+        self::assertSame(['chat'], SocketRegistry::names());
+    }
+    public function testUnknownNameResolvesToNull(): void
+    {
+        self::assertNull(SocketRegistry::get('nope'));
+    }
+    public function testDuplicateNameIsRefused(): void
+    {
+        SocketRegistry::register('chat', static function (): void {});
+        $this->expectException(InvalidArgumentException::class);
+        SocketRegistry::register('chat', static function (): void {});
+    }
+    public function testEmptyNameIsRefused(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        SocketRegistry::register('', static function (): void {});
+    }
+}

package/dist/tests/SocketTest.php ADDED Viewed

@@ -0,0 +1,124 @@
+<?php
+declare(strict_types=1);
+namespace Tests;
+use InvalidArgumentException;
+use Lib\Websocket\Socket;
+use PHPUnit\Framework\TestCase;
+use Tests\Support\FakeConnection;
+use Tests\Support\RequiresFeature;
+/**
+ * One open connection, as a socket handler holds it: JSON frames out, the
+ * reserved `{"error": ...}` shape refused, and close semantics.
+ */
+final class SocketTest extends TestCase
+{
+    use RequiresFeature;
+    protected function setUp(): void
+    {
+        $this->requireFeature('websocket');
+    }
+    public function testSendEncodesOneJsonValuePerFrame(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+        self::assertTrue($socket->send(['text' => 'hello']));
+        self::assertTrue($socket->send('plain'));
+        self::assertTrue($socket->send(42));
+        self::assertSame([['text' => 'hello'], 'plain', 42], $conn->sentFrames);
+    }
+    public function testSendRefusesTheReservedErrorShape(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+        $this->expectException(InvalidArgumentException::class);
+        $socket->send(['error' => 'looks like a failure frame']);
+    }
+    public function testAPayloadThatMerelyContainsAnErrorKeyIsSendable(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+        self::assertTrue($socket->send(['error' => 'mine', 'other' => 1]));
+        self::assertSame(['error' => 'mine', 'other' => 1], $conn->lastFrame());
+    }
+    public function testSendAfterCloseReturnsFalse(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+        $socket->handleClose();
+        self::assertFalse($socket->send('late'));
+        self::assertSame([], $conn->sentFrames);
+    }
+    public function testMessageListenerReceivesDecodedValues(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+        $seen = [];
+        $socket->onMessage(function (mixed $value) use (&$seen): void {
+            $seen[] = $value;
+        });
+        $socket->handleMessage(['text' => 'hi']);
+        $socket->handleMessage('plain');
+        self::assertSame([['text' => 'hi'], 'plain'], $seen);
+    }
+    public function testCloseListenerFiresExactlyOnce(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo');
+        $closes = 0;
+        $socket->onClose(function () use (&$closes): void {
+            $closes++;
+        });
+        $socket->handleClose();
+        $socket->handleClose();
+        self::assertSame(1, $closes);
+        self::assertFalse($socket->isOpen());
+    }
+    public function testErrorSendsTheReservedFrameThenCloses(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+        $socket->error('no such room');
+        self::assertSame(['error' => 'no such room'], $conn->lastFrame());
+        self::assertSame([1008], $conn->closeCodes);
+    }
+    public function testCloseUsesNormalClosure(): void
+    {
+        $conn = new FakeConnection();
+        $socket = new Socket($conn, 'echo');
+        $socket->close();
+        self::assertSame([1000], $conn->closeCodes);
+    }
+    public function testPayloadIsHandedToTheHandler(): void
+    {
+        $socket = new Socket(new FakeConnection(), 'echo', ['role' => 'admin']);
+        self::assertSame(['role' => 'admin'], $socket->payload());
+    }
+}