@ggui-ai/protocol-conformance 0.1.0-rc.1

package/dist/registration-conformance/cases/gate-typo-classifies-as-not-registered.json

@@ -0,0 +1,27 @@
+{
+    "name": "gate-typo-classifies-as-not-registered",
+    "description": "The contract references `useGeoLocation` (capital L) under `@ggui-ai/gadgets` — a near-miss typo of the registered `useGeolocation`. A typo'd export name is still an export name absent from every registered package, so the gate MUST classify it as `gadget_not_registered`, NOT `gadget_package_mismatch` (the name does not resolve under any package). The reference gate additionally attaches a did-you-mean suggestion when a registered name is within Levenshtein distance < 3; the suggestion is a message-level aid and does not change the outcome code this catalog asserts.",
+    "contract": {
+        "clientCapabilities": {
+            "gadgets": {
+                "@ggui-ai/gadgets": { "useGeoLocation": {} }
+            }
+        }
+    },
+    "appGadgets": [
+        {
+            "package": "@ggui-ai/gadgets",
+            "version": "1.0.0",
+            "exports": [
+                { "hook": "useCamera" },
+                { "hook": "useClipboardPaste" },
+                { "hook": "useClipboardWrite" },
+                { "hook": "useFilePicker" },
+                { "hook": "useGeolocation" },
+                { "hook": "useMicrophone" },
+                { "hook": "useNotifications" }
+            ]
+        }
+    ],
+    "expect": { "outcome": "reject", "code": "gadget_not_registered" }
+}

package/dist/registration-conformance/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Registration-conformance catalog — accept / reject cases for the
+ * gadget push-time registry gate (SPEC §7.7.2 — `assertGadgetsRegistered`).
+ *
+ * ## Why this is a pure-function catalog, not a behavioral fixture
+ *
+ * The push-time gadget gate answers a pure question: given a contract
+ * and the app's registered `App.gadgets` catalog, does every
+ * `(package, export)` the contract references resolve — and if not,
+ * which precise reject code applies? There is no session, no
+ * transport, no wire frame in that question — it is a deterministic
+ * classification, exactly like the `clientCapabilities` schema check
+ * in `../schema-conformance`.
+ *
+ * Modeling it as a WebSocket behavioral fixture would mean inventing a
+ * wire frame the real protocol never emits (the gate runs at MCP-push
+ * time, before any live channel exists) — the dishonest modeling the
+ * kit's Path-A / Path-B partition exists to forbid. So the gate gets
+ * the same treatment as the wire schema: a catalog of cases graded
+ * against a caller-supplied gate function.
+ *
+ * ## Polyglot, decoupled
+ *
+ * Each case ships as raw JSON under `./cases/`. {@link runRegistrationConformance}
+ * takes the gate as a callback — the kit never imports a concrete gate
+ * implementation here, so adopters drive their OWN gate. The reference
+ * binding (`./registration-conformance.test.ts`) wraps
+ * `@ggui-ai/mcp-server-handlers`'s `assertGadgetsRegistered`.
+ *
+ * The `DataContract` / `GadgetDescriptor` types ARE imported (type-only)
+ * from `@ggui-ai/protocol` — unlike the behavioral fixture vocabulary
+ * in `../types.ts`, these are the gate's actual input contract, not a
+ * frozen authored union; the runner's `gate` signature MUST match the
+ * real function for the reference binding to be cast-free.
+ */
+import type { DataContract, GadgetDescriptor } from '@ggui-ai/protocol';
+/**
+ * The precise reject codes the gadget gate classifies a miss into.
+ * Mirrors `GadgetGateErrorCode`'s registry-gate arms in
+ * `@ggui-ai/mcp-server-handlers`. Extensibly-closed `(string & {})`
+ * tail so a later protocol revision's code rides through without a kit
+ * bump — same discipline as `ContractErrorCode` in `../types.ts`.
+ */
+export type GadgetGateRejectCode = 'gadget_not_registered' | 'gadget_package_mismatch' | (string & {});
+/**
+ * The outcome of running the gate against one `(contract, appGadgets)`
+ * pair. A conformant gate either accepts the push or rejects it with
+ * one classified code.
+ */
+export type GateOutcome = {
+    readonly outcome: 'accept';
+} | {
+    readonly outcome: 'reject';
+    readonly code: GadgetGateRejectCode;
+};
+/**
+ * One registration-conformance case. Authored as JSON under `./cases/`,
+ * consumed via {@link gadgetRegistrationCases}, graded by
+ * {@link runRegistrationConformance}.
+ *
+ * The shape IS the public API — additive changes only, mirroring the
+ * `TestCase` / `SchemaConformanceCase` discipline.
+ */
+export interface RegistrationConformanceCase {
+    /** Unique case name. MUST match the JSON filename without `.json`. */
+    readonly name: string;
+    /** What gate obligation this case proves. */
+    readonly description: string;
+    /** The contract whose `clientCapabilities.gadgets` the gate walks. */
+    readonly contract: DataContract;
+    /** The app's registered gadget catalog the gate resolves against. */
+    readonly appGadgets: readonly GadgetDescriptor[];
+    /** The outcome a spec-conformant gate MUST produce. */
+    readonly expect: GateOutcome;
+}
+/**
+ * Every gadget registration-gate case the kit ships, in deterministic
+ * order — rejects first (grouped by the obligation they probe), then
+ * accepts.
+ */
+export declare const gadgetRegistrationCases: readonly RegistrationConformanceCase[];
+/** One case the gate under test graded wrong. */
+export interface RegistrationConformanceMismatch {
+    readonly name: string;
+    /** The outcome the catalog says a conformant gate MUST produce. */
+    readonly expected: GateOutcome;
+    /** The outcome the gate under test actually produced. */
+    readonly actual: GateOutcome;
+}
+/** Outcome of grading a gate against the catalog. */
+export interface RegistrationConformanceResult {
+    /** Names of cases the gate graded correctly. */
+    readonly passed: readonly string[];
+    /** Cases the gate graded wrong — empty iff fully conformant. */
+    readonly failed: readonly RegistrationConformanceMismatch[];
+}
+/**
+ * Grade a gadget registration gate against the catalog.
+ *
+ * `gate` MUST be a pure classification of `(contract, appGadgets)` —
+ * return `{outcome:'accept'}` when every referenced `(package, export)`
+ * resolves, or `{outcome:'reject', code}` with the precise reject code
+ * otherwise. The kit deliberately does NOT import a concrete gate —
+ * adopters pass their own (the reference binding wraps
+ * `assertGadgetsRegistered`; see `./registration-conformance.test.ts`).
+ * A conformant gate produces an empty `failed` array.
+ *
+ * `gate` is invoked exactly once per case, in {@link gadgetRegistrationCases}
+ * order; it MUST be pure and MUST NOT throw (a throwing gate is itself
+ * non-conformant — wrap it so a classified rejection becomes a
+ * returned `GateOutcome`).
+ */
+export declare function runRegistrationConformance(gate: (contract: DataContract, appGadgets: readonly GadgetDescriptor[]) => GateOutcome): RegistrationConformanceResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/registration-conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registration-conformance/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAUxE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B,uBAAuB,GACvB,yBAAyB,GACzB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,2BAA2B,EAQzE,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,6BAA6B;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAC7D;AAUD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,CACJ,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,SAAS,gBAAgB,EAAE,KACpC,WAAW,GACf,6BAA6B,CAgB/B"}

package/dist/registration-conformance/index.js

@@ -0,0 +1,63 @@
+import gateExportNotRegistered from './cases/gate-export-not-registered.json' with { type: 'json' };
+import gateNoGadgetsAccept from './cases/gate-no-gadgets-accept.json' with { type: 'json' };
+import gatePackageMismatch from './cases/gate-package-mismatch.json' with { type: 'json' };
+import gatePriorityNotRegisteredOutranksMismatch from './cases/gate-priority-not-registered-outranks-mismatch.json' with { type: 'json' };
+import gateRegisteredResolvesAccept from './cases/gate-registered-resolves-accept.json' with { type: 'json' };
+import gateStdlibHookAccept from './cases/gate-stdlib-hook-accept.json' with { type: 'json' };
+import gateTypoClassifiesAsNotRegistered from './cases/gate-typo-classifies-as-not-registered.json' with { type: 'json' };
+/**
+ * Every gadget registration-gate case the kit ships, in deterministic
+ * order — rejects first (grouped by the obligation they probe), then
+ * accepts.
+ */
+export const gadgetRegistrationCases = [
+    gateExportNotRegistered,
+    gatePackageMismatch,
+    gatePriorityNotRegisteredOutranksMismatch,
+    gateTypoClassifiesAsNotRegistered,
+    gateStdlibHookAccept,
+    gateRegisteredResolvesAccept,
+    gateNoGadgetsAccept,
+];
+function gateOutcomeEquals(a, b) {
+    if (a.outcome !== b.outcome)
+        return false;
+    if (a.outcome === 'reject' && b.outcome === 'reject') {
+        return a.code === b.code;
+    }
+    return true;
+}
+/**
+ * Grade a gadget registration gate against the catalog.
+ *
+ * `gate` MUST be a pure classification of `(contract, appGadgets)` —
+ * return `{outcome:'accept'}` when every referenced `(package, export)`
+ * resolves, or `{outcome:'reject', code}` with the precise reject code
+ * otherwise. The kit deliberately does NOT import a concrete gate —
+ * adopters pass their own (the reference binding wraps
+ * `assertGadgetsRegistered`; see `./registration-conformance.test.ts`).
+ * A conformant gate produces an empty `failed` array.
+ *
+ * `gate` is invoked exactly once per case, in {@link gadgetRegistrationCases}
+ * order; it MUST be pure and MUST NOT throw (a throwing gate is itself
+ * non-conformant — wrap it so a classified rejection becomes a
+ * returned `GateOutcome`).
+ */
+export function runRegistrationConformance(gate) {
+    const passed = [];
+    const failed = [];
+    for (const testCase of gadgetRegistrationCases) {
+        const actual = gate(testCase.contract, testCase.appGadgets);
+        if (gateOutcomeEquals(actual, testCase.expect)) {
+            passed.push(testCase.name);
+        }
+        else {
+            failed.push({
+                name: testCase.name,
+                expected: testCase.expect,
+                actual,
+            });
+        }
+    }
+    return { passed, failed };
+}

package/dist/reporter.d.ts

@@ -0,0 +1,32 @@
+import type { ConformanceFailure, ConformanceReporter, ConformanceResult, SkippedFixture } from './run-conformance.js';
+export interface DefaultReporterOptions {
+    /**
+     * Destination for all output. Defaults to
+     * `process.stdout.write`-bound. Tests swap this for capture.
+     */
+    readonly write?: (line: string) => void;
+    /**
+     * If `true`, emit one line per fixture as it completes (streaming).
+     * If `false`, only emit the final summary block. Default `true`.
+     */
+    readonly streaming?: boolean;
+}
+/**
+ * Build a {@link ConformanceReporter} that writes the bar-scorecard
+ * report. The return value plugs directly into
+ * `runConformance({reporter: createDefaultReporter()})`.
+ */
+export declare function createDefaultReporter(options?: DefaultReporterOptions): ConformanceReporter;
+export declare function formatScorecard(result: ConformanceResult): string;
+export declare function formatSummary(result: ConformanceResult): string;
+/**
+ * Emit the full set of failure messages — for CLI `--verbose` mode +
+ * programmatic consumers that want a post-run diagnostic dump.
+ */
+export declare function formatFailures(failures: readonly ConformanceFailure[]): string;
+/**
+ * Emit the full set of skip reasons — useful for `--verbose` mode to
+ * see which directives an implementation hasn't wired yet.
+ */
+export declare function formatSkips(skipped: readonly SkippedFixture[]): string;
+//# sourceMappingURL=reporter.d.ts.map

package/dist/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,mBAAmB,CA0CrB;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAmBjE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAW/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAW9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAStE"}

package/dist/reporter.js

@@ -0,0 +1,151 @@
+/**
+ * Default reporter implementation for `runConformance()`.
+ *
+ * Prints a scorecard-style report to stdout as fixtures complete,
+ * then a summary block at the end grouped by contract slug. The
+ * output groups results by the protocol/contract criterion each
+ * fixture exercises so adopters can see at a glance which obligations
+ * their implementation satisfies.
+ *
+ * The default reporter is `process.stdout`-bound. Third-party
+ * consumers wanting programmatic access should implement
+ * {@link ConformanceReporter} directly against their own sink (JSON,
+ * vitest, CI annotations, etc.) and pass it via `runConformance()`'s
+ * `reporter` config.
+ */
+import { fixturesByContract } from './fixtures/index.js';
+/**
+ * Build a {@link ConformanceReporter} that writes the bar-scorecard
+ * report. The return value plugs directly into
+ * `runConformance({reporter: createDefaultReporter()})`.
+ */
+export function createDefaultReporter(options = {}) {
+    const write = options.write ??
+        ((line) => {
+            process.stdout.write(line);
+            if (!line.endsWith('\n'))
+                process.stdout.write('\n');
+        });
+    const streaming = options.streaming ?? true;
+    return {
+        onStart(total) {
+            if (!streaming)
+                return;
+            write(`ggui protocol conformance — driving ${total} fixture(s) against the implementation under test`);
+            write(RULE);
+        },
+        onFixturePass(name, elapsedMs) {
+            if (!streaming)
+                return;
+            write(`  ${MARK_PASS}  ${padRight(name, 48)}  ${elapsedMs}ms`);
+        },
+        onFixtureFail(failure) {
+            if (!streaming)
+                return;
+            write(`  ${MARK_FAIL}  ${padRight(failure.name, 48)}  ${failure.criterion}`);
+            write(`        → ${failure.message}`);
+        },
+        onFixtureSkip(name, reason) {
+            if (!streaming)
+                return;
+            const shortReason = reason.length > 80 ? `${reason.slice(0, 77)}…` : reason;
+            write(`  ${MARK_SKIP}  ${padRight(name, 48)}  ${shortReason}`);
+        },
+        onTeardownWarning(name, message) {
+            if (!streaming)
+                return;
+            write(`  ${MARK_WARN}  ${padRight(name, 48)}  teardown: ${message}`);
+        },
+        onComplete(result) {
+            write(RULE);
+            write(formatScorecard(result));
+            write(RULE);
+            write(formatSummary(result));
+        },
+    };
+}
+// =============================================================================
+// Scorecard formatting
+// =============================================================================
+export function formatScorecard(result) {
+    // Group fixtures by contract so operators see pass rates per
+    // criterion, mirroring `fixturesByContract`'s classification.
+    const lines = [];
+    for (const [slug, fixtures] of Object.entries(fixturesByContract)) {
+        const names = new Set(fixtures.map((f) => f.name));
+        const passedCount = result.passed.filter((n) => names.has(n)).length;
+        const failedCount = result.failed.filter((f) => names.has(f.name)).length;
+        const skippedCount = result.skipped.filter((s) => names.has(s.name)).length;
+        const total = passedCount + failedCount + skippedCount;
+        if (total === 0)
+            continue;
+        const tone = failedCount > 0 ? MARK_FAIL : passedCount > 0 ? MARK_PASS : MARK_SKIP;
+        lines.push(`  ${tone}  ${padRight(slug, 38)}  ${passedCount}/${total} pass${failedCount > 0 ? ` · ${failedCount} fail` : ''}${skippedCount > 0 ? ` · ${skippedCount} skip` : ''}`);
+    }
+    return lines.join('\n');
+}
+export function formatSummary(result) {
+    const passed = result.passed.length;
+    const failed = result.failed.length;
+    const skipped = result.skipped.length;
+    const total = passed + failed + skipped;
+    return [
+        `  Passed:   ${String(passed).padStart(3)}`,
+        `  Failed:   ${String(failed).padStart(3)}`,
+        `  Skipped:  ${String(skipped).padStart(3)}`,
+        `  Total:    ${String(total).padStart(3)}   (${result.totalMs}ms)`,
+    ].join('\n');
+}
+/**
+ * Emit the full set of failure messages — for CLI `--verbose` mode +
+ * programmatic consumers that want a post-run diagnostic dump.
+ */
+export function formatFailures(failures) {
+    if (failures.length === 0)
+        return '';
+    const lines = ['', 'Failures:', ''];
+    for (const failure of failures) {
+        lines.push(`${MARK_FAIL} ${failure.name}  (${failure.criterion})`);
+        lines.push(`   ${failure.message}`);
+        lines.push(`   expected: ${safeStringify(failure.expected)}`);
+        lines.push(`   received: ${safeStringify(failure.received)}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Emit the full set of skip reasons — useful for `--verbose` mode to
+ * see which directives an implementation hasn't wired yet.
+ */
+export function formatSkips(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const lines = ['', 'Skipped:', ''];
+    for (const skip of skipped) {
+        lines.push(`${MARK_SKIP} ${skip.name}`);
+        lines.push(`   ${skip.reason}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// =============================================================================
+// Shared glyphs + helpers
+// =============================================================================
+const RULE = '─'.repeat(70);
+const MARK_PASS = 'PASS';
+const MARK_FAIL = 'FAIL';
+const MARK_SKIP = 'SKIP';
+const MARK_WARN = 'WARN';
+function padRight(s, width) {
+    if (s.length >= width)
+        return s;
+    return s + ' '.repeat(width - s.length);
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/resolution-conformance/cases/resolve-bundle-host-computed.json

@@ -0,0 +1,13 @@
+{
+    "name": "resolve-bundle-host-computed",
+    "description": "A descriptor with a hostname-only `bundleHost` (no scheme, no path) and no explicit `bundleUrl`. The resolver MUST compute both the bundle and style URLs as `https://<bundleHost>/bundles/<package>/<version>/<file>` — the path layout matching `@ggui-ai/registry-core`'s `BundleStorage` so a bundle published to one registry resolves cleanly from the other.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper",
+        "version": "2.3.1",
+        "bundleHost": "cdn.example.com"
+    },
+    "expect": {
+        "bundleUrl": "https://cdn.example.com/bundles/@acme/leaflet-wrapper/2.3.1/bundle.js",
+        "styleUrl": "https://cdn.example.com/bundles/@acme/leaflet-wrapper/2.3.1/style.css"
+    }
+}

package/dist/resolution-conformance/cases/resolve-default-host.json

@@ -0,0 +1,12 @@
+{
+    "name": "resolve-default-host",
+    "description": "A descriptor with `package` + `version` but neither `bundleHost` nor `bundleUrl`. The resolver MUST fall through to the spec default host `registry.ggui.ai` — first-party and hosted-registry publishes resolve with zero operator config.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper",
+        "version": "2.3.1"
+    },
+    "expect": {
+        "bundleUrl": "https://registry.ggui.ai/bundles/@acme/leaflet-wrapper/2.3.1/bundle.js",
+        "styleUrl": "https://registry.ggui.ai/bundles/@acme/leaflet-wrapper/2.3.1/style.css"
+    }
+}

package/dist/resolution-conformance/cases/resolve-explicit-bundle-and-style-url.json

@@ -0,0 +1,14 @@
+{
+    "name": "resolve-explicit-bundle-and-style-url",
+    "description": "Both `bundleUrl` and `styleUrl` declared explicitly. Each is a full-URL escape hatch and MUST be used verbatim — no hostname computation, no path assembly.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper",
+        "version": "2.3.1",
+        "bundleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/bundle.js",
+        "styleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/style.css"
+    },
+    "expect": {
+        "bundleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/bundle.js",
+        "styleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/style.css"
+    }
+}

package/dist/resolution-conformance/cases/resolve-explicit-bundle-url.json

@@ -0,0 +1,12 @@
+{
+    "name": "resolve-explicit-bundle-url",
+    "description": "A descriptor with an explicit full `bundleUrl` — the escape hatch for wrappers shipped via a non-registry CDN (esm.sh, jsdelivr, …). The resolver MUST use `bundleUrl` verbatim and MUST NOT auto-synthesize a `styleUrl`: an operator who escape-hatched the bundle declares `styleUrl` themselves, and a synthesized `registry.ggui.ai/.../style.css` would 404 and pollute the iframe CSP `style-src`.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper",
+        "version": "2.3.1",
+        "bundleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/bundle.js"
+    },
+    "expect": {
+        "bundleUrl": "https://esm.sh/@acme/leaflet-wrapper@2.3.1/bundle.js"
+    }
+}

package/dist/resolution-conformance/cases/resolve-loopback-host-http-scheme.json

@@ -0,0 +1,13 @@
+{
+    "name": "resolve-loopback-host-http-scheme",
+    "description": "A `bundleHost` resolving to localhost (`localhost`, `127.0.0.1`, or `0.0.0.0`, each optionally with a port). The resolver MUST emit the `http://` scheme for loopback hosts: a local-registry workflow publishes over `http://`, and an `https://` render URL would mixed-content-block in the sandboxed iframe. Every non-loopback host gets `https://`.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper",
+        "version": "2.3.1",
+        "bundleHost": "localhost:4873"
+    },
+    "expect": {
+        "bundleUrl": "http://localhost:4873/bundles/@acme/leaflet-wrapper/2.3.1/bundle.js",
+        "styleUrl": "http://localhost:4873/bundles/@acme/leaflet-wrapper/2.3.1/style.css"
+    }
+}

package/dist/resolution-conformance/cases/resolve-package-only-no-version.json

@@ -0,0 +1,8 @@
+{
+    "name": "resolve-package-only-no-version",
+    "description": "A descriptor with a `package` but no `version` — not enough to assemble a hostable bundle path. The resolver MUST return no URLs (such an entry is resolved iframe-side via a bare-specifier `package` import, no bundle URL needed). Guards against a resolver that emits a malformed `.../undefined/bundle.js`.",
+    "entry": {
+        "package": "@acme/leaflet-wrapper"
+    },
+    "expect": {}
+}

package/dist/resolution-conformance/cases/resolve-stdlib-no-urls.json

@@ -0,0 +1,10 @@
+{
+    "name": "resolve-stdlib-no-urls",
+    "description": "The first-party `@ggui-ai/gadgets` stdlib package. Its exports ship with the iframe runtime — no bundle is fetched. The resolver MUST return no URLs for it, and MUST do so even when a `bundleUrl` is present: the stdlib's transport is first-party by construction and operators do not override it.",
+    "entry": {
+        "package": "@ggui-ai/gadgets",
+        "version": "1.0.0",
+        "bundleUrl": "https://example.com/should-be-ignored.js"
+    },
+    "expect": {}
+}

package/dist/resolution-conformance/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The transport-relevant subset of a gadget descriptor the resolver
+ * reads. Authored loose — every field optional — because the resolver
+ * is defined to defensively handle incomplete entries (a `package`
+ * with no `version`, etc.). Decoupled from `@ggui-ai/protocol`'s
+ * `GadgetDescriptor` on purpose: this is the kit's authored vocabulary.
+ */
+export interface GadgetUrlEntry {
+    readonly package?: string;
+    readonly version?: string;
+    readonly bundleUrl?: string;
+    readonly bundleHost?: string;
+    readonly styleUrl?: string;
+}
+/**
+ * What the resolver produces — the bundle + style URLs (either may be
+ * absent: an escape-hatched bundle synthesizes no style, a stdlib or
+ * version-less entry resolves to neither).
+ */
+export interface ResolvedGadgetUrls {
+    readonly bundleUrl?: string;
+    readonly styleUrl?: string;
+}
+/**
+ * One resolution-conformance case. Authored as JSON under `./cases/`,
+ * consumed via {@link gadgetResolutionCases}, graded by
+ * {@link runResolutionConformance}.
+ *
+ * The shape IS the public API — additive changes only.
+ */
+export interface ResolutionConformanceCase {
+    /** Unique case name. MUST match the JSON filename without `.json`. */
+    readonly name: string;
+    /** Which resolution obligation this case proves. */
+    readonly description: string;
+    /** The descriptor transport fields fed to the resolver. */
+    readonly entry: GadgetUrlEntry;
+    /** The URLs a spec-conformant resolver MUST produce. */
+    readonly expect: ResolvedGadgetUrls;
+}
+/**
+ * Every gadget URL-resolution case the kit ships, in deterministic
+ * order — explicit-URL cases, then host-computed, then the
+ * no-resolution edges.
+ */
+export declare const gadgetResolutionCases: readonly ResolutionConformanceCase[];
+/** One case the resolver under test graded wrong. */
+export interface ResolutionConformanceMismatch {
+    readonly name: string;
+    /** The URLs the catalog says a conformant resolver MUST produce. */
+    readonly expected: ResolvedGadgetUrls;
+    /** The URLs the resolver under test actually produced. */
+    readonly actual: ResolvedGadgetUrls;
+}
+/** Outcome of grading a resolver against the catalog. */
+export interface ResolutionConformanceResult {
+    /** Names of cases the resolver graded correctly. */
+    readonly passed: readonly string[];
+    /** Cases the resolver graded wrong — empty iff fully conformant. */
+    readonly failed: readonly ResolutionConformanceMismatch[];
+}
+/**
+ * Grade a gadget URL resolver against the catalog.
+ *
+ * `resolve` MUST be a pure computation of `(entry) → {bundleUrl?,
+ * styleUrl?}`. The kit deliberately does NOT import a concrete
+ * resolver — adopters pass their own (the reference binding uses a
+ * faithful in-test resolver; see `./resolution-conformance.test.ts`).
+ * A conformant resolver produces an empty `failed` array.
+ *
+ * `resolve` is invoked exactly once per case, in
+ * {@link gadgetResolutionCases} order; it MUST be pure and MUST NOT
+ * throw.
+ */
+export declare function runResolutionConformance(resolve: (entry: GadgetUrlEntry) => ResolvedGadgetUrls): ResolutionConformanceResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/resolution-conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resolution-conformance/index.ts"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,yBAAyB,EAQrE,CAAC;AAEF,qDAAqD;AACrD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED,yDAAyD;AACzD,MAAM,WAAW,2BAA2B;IAC1C,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC3D;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,kBAAkB,GACrD,2BAA2B,CAgB7B"}

package/dist/resolution-conformance/index.js

@@ -0,0 +1,81 @@
+/**
+ * Resolution-conformance catalog — accept cases for gadget bundle-URL
+ * resolution (SPEC §7.7.2 — `resolveGadgetUrls`).
+ *
+ * ## Why this is a pure-function catalog
+ *
+ * Given a gadget descriptor's transport fields, the server computes
+ * the bundle + style URLs the iframe sees in
+ * `_meta.ggui.bootstrap.gadgets[*]`. That computation is a pure,
+ * deterministic function — no session, transport, or wire frame — so
+ * it gets the same treatment as the wire schema (`../schema-conformance`)
+ * and the registry gate (`../registration-conformance`): a catalog of
+ * cases graded against a caller-supplied resolver.
+ *
+ * Every case here is an "accept"-shaped check — the resolver always
+ * produces *some* result; the obligation is which URLs (or none).
+ *
+ * ## Polyglot, decoupled
+ *
+ * Each case ships as raw JSON under `./cases/`.
+ * {@link runResolutionConformance} takes the resolver as a callback —
+ * the kit never imports a concrete resolver here, so adopters drive
+ * their OWN. The reference binding (`./resolution-conformance.test.ts`)
+ * uses a faithful in-test resolver built from `@ggui-ai/protocol`'s
+ * `DEFAULT_BUNDLE_HOST` + `bundleHostScheme` primitives.
+ */
+import resolveBundleHostComputed from './cases/resolve-bundle-host-computed.json' with { type: 'json' };
+import resolveDefaultHost from './cases/resolve-default-host.json' with { type: 'json' };
+import resolveExplicitBundleAndStyleUrl from './cases/resolve-explicit-bundle-and-style-url.json' with { type: 'json' };
+import resolveExplicitBundleUrl from './cases/resolve-explicit-bundle-url.json' with { type: 'json' };
+import resolveLoopbackHostHttpScheme from './cases/resolve-loopback-host-http-scheme.json' with { type: 'json' };
+import resolvePackageOnlyNoVersion from './cases/resolve-package-only-no-version.json' with { type: 'json' };
+import resolveStdlibNoUrls from './cases/resolve-stdlib-no-urls.json' with { type: 'json' };
+/**
+ * Every gadget URL-resolution case the kit ships, in deterministic
+ * order — explicit-URL cases, then host-computed, then the
+ * no-resolution edges.
+ */
+export const gadgetResolutionCases = [
+    resolveExplicitBundleUrl,
+    resolveExplicitBundleAndStyleUrl,
+    resolveBundleHostComputed,
+    resolveDefaultHost,
+    resolveLoopbackHostHttpScheme,
+    resolveStdlibNoUrls,
+    resolvePackageOnlyNoVersion,
+];
+function resolvedUrlsEqual(a, b) {
+    return a.bundleUrl === b.bundleUrl && a.styleUrl === b.styleUrl;
+}
+/**
+ * Grade a gadget URL resolver against the catalog.
+ *
+ * `resolve` MUST be a pure computation of `(entry) → {bundleUrl?,
+ * styleUrl?}`. The kit deliberately does NOT import a concrete
+ * resolver — adopters pass their own (the reference binding uses a
+ * faithful in-test resolver; see `./resolution-conformance.test.ts`).
+ * A conformant resolver produces an empty `failed` array.
+ *
+ * `resolve` is invoked exactly once per case, in
+ * {@link gadgetResolutionCases} order; it MUST be pure and MUST NOT
+ * throw.
+ */
+export function runResolutionConformance(resolve) {
+    const passed = [];
+    const failed = [];
+    for (const testCase of gadgetResolutionCases) {
+        const actual = resolve(testCase.entry);
+        if (resolvedUrlsEqual(actual, testCase.expect)) {
+            passed.push(testCase.name);
+        }
+        else {
+            failed.push({
+                name: testCase.name,
+                expected: testCase.expect,
+                actual,
+            });
+        }
+    }
+    return { passed, failed };
+}