@fuzdev/fuz_app 0.63.0 → 0.65.0

package/dist/testing/surface_invariants.d.ts

@@ -96,6 +96,52 @@ export interface ErrorSchemaAuditEntry {
  * @returns audit entries for every route x status combination
  */
 export declare const audit_error_schema_tightness: (surface: AppSurface) => Array<ErrorSchemaAuditEntry>;
+/**
+ * Every RPC method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.rpc_endpoints`.
+ * Empty descriptions on RPC methods leak through `library.json` codegen and
+ * consumer-facing docs without the route-level check catching them.
+ */
+export declare const assert_rpc_method_descriptions_present: (surface: AppSurface) => void;
+/**
+ * Every WS method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.ws_endpoints`.
+ * Same rationale as `assert_rpc_method_descriptions_present` — codegen +
+ * surface explorer consume the description, blank values surface as `''`.
+ */
+export declare const assert_ws_method_descriptions_present: (surface: AppSurface) => void;
+/**
+ * Every WS endpoint's `methods` includes every protocol action method
+ * (`heartbeat`, `cancel`).
+ *
+ * Consumers register WS endpoints by spreading `protocol_actions` from
+ * `actions/protocol.ts` before their own actions:
+ *
+ * ```ts
+ * ws_endpoints: [{path: '/api/ws', actions: [...protocol_actions, ...consumer_actions], ...}]
+ * ```
+ *
+ * Forgetting the spread compiles cleanly but breaks at runtime: client-side
+ * heartbeats and `cancel` notifications get `method_not_found` from the
+ * dispatcher, so disconnect detection silently regresses and per-request
+ * cancel never aborts the matching handler. Catch the mistake at the
+ * surface layer rather than at runtime.
+ */
+export declare const assert_ws_endpoints_include_protocol_actions: (surface: AppSurface) => void;
+/**
+ * WS methods follow the kind ⇔ auth biconditional emitted by surface
+ * generation: `kind === 'remote_notification' ⟺ auth === null`.
+ *
+ * `generate_app_surface` produces this shape directly from the action
+ * spec union (notifications carry `auth: null` per `ActionSpecUnion`;
+ * `request_response` carries a `RouteAuth`). The assertion guards against
+ * drift if a future surface emitter, transform, or test fixture violates
+ * it — and gives consumers a clear failure message when a hand-built
+ * surface mocks the shape incorrectly.
+ */
+export declare const assert_ws_notifications_have_null_auth: (surface: AppSurface) => void;
 /**
  * Configuration for security policy invariants.
  *
@@ -146,7 +192,9 @@ export declare const assert_no_unexpected_public_mutations: (surface: AppSurface
  *
  * Note: RPC endpoints (`create_rpc_endpoint`) use `input: z.null()` on their
  * route specs — the dispatcher handles body/query parsing internally. Real input
- * schemas live in `rpc_endpoints` surface, not on routes.
+ * schemas live in `rpc_endpoints` surface, not on routes; see
+ * `assert_rpc_ws_surface_invariants` for the parallel checks over RPC/WS
+ * method shapes.
  */
 export declare const assert_mutation_routes_use_post: (surface: AppSurface) => void;
 /**
@@ -223,6 +271,23 @@ export declare const assert_error_schema_tightness: (surface: AppSurface, option
  *   the offending route and the missing/inconsistent field.
  */
 export declare const assert_surface_invariants: (surface: AppSurface) => void;
+/**
+ * Run all RPC / WS structural invariants. Options-free — applies
+ * universally to the `surface.rpc_endpoints` and `surface.ws_endpoints`
+ * slots produced by `generate_app_surface`.
+ *
+ * Parallel of `assert_surface_invariants` for the non-REST surfaces.
+ * Within-endpoint duplicate method names and the auth-shape biconditional
+ * are already enforced at startup by `compile_action_registry` (see
+ * `actions/CLAUDE.md` §Registry compile) — these assertions cover only
+ * the contract-surface concerns that a runtime registration check
+ * cannot: empty descriptions, missing protocol-action spread on WS
+ * endpoints, and kind ⇔ auth drift on WS methods.
+ *
+ * @throws AssertionError on the first invariant violation; the message
+ *   names the offending endpoint, method, and field.
+ */
+export declare const assert_rpc_ws_surface_invariants: (surface: AppSurface) => void;
 /**
  * Run security policy invariants. Configurable with sensible defaults.
  *

package/dist/testing/surface_invariants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface_invariants.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/surface_invariants.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface_invariants.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/surface_invariants.ts"],"names":[],"mappings":"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"}

package/dist/testing/surface_invariants.js

@@ -19,6 +19,7 @@ import './assert_dev_env.js';
 import { assert } from 'vitest';
 import { middleware_applies } from '../http/schema_helpers.js';
 import { filter_protected_routes, filter_role_routes, filter_keeper_routes, filter_routes_with_input, filter_routes_with_params, filter_routes_with_query, filter_public_routes, format_route_key, } from '../http/surface_query.js';
+import { PROTOCOL_ACTION_METHODS } from '../actions/action_codegen.js';
 // --- Structural invariants ---
 /**
  * Every protected route has 401 in `error_schemas`.
@@ -374,6 +375,83 @@ export const audit_error_schema_tightness = (surface) => {
     }
     return entries;
 };
+// --- RPC / WS structural invariants ---
+/**
+ * Every RPC method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.rpc_endpoints`.
+ * Empty descriptions on RPC methods leak through `library.json` codegen and
+ * consumer-facing docs without the route-level check catching them.
+ */
+export const assert_rpc_method_descriptions_present = (surface) => {
+    for (const ep of surface.rpc_endpoints) {
+        for (const method of ep.methods) {
+            assert.ok(method.description.length > 0, `RPC method '${method.name}' on endpoint '${ep.path}' has empty description`);
+        }
+    }
+};
+/**
+ * Every WS method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.ws_endpoints`.
+ * Same rationale as `assert_rpc_method_descriptions_present` — codegen +
+ * surface explorer consume the description, blank values surface as `''`.
+ */
+export const assert_ws_method_descriptions_present = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        for (const method of ep.methods) {
+            assert.ok(method.description.length > 0, `WS method '${method.name}' on endpoint '${ep.path}' has empty description`);
+        }
+    }
+};
+/**
+ * Every WS endpoint's `methods` includes every protocol action method
+ * (`heartbeat`, `cancel`).
+ *
+ * Consumers register WS endpoints by spreading `protocol_actions` from
+ * `actions/protocol.ts` before their own actions:
+ *
+ * ```ts
+ * ws_endpoints: [{path: '/api/ws', actions: [...protocol_actions, ...consumer_actions], ...}]
+ * ```
+ *
+ * Forgetting the spread compiles cleanly but breaks at runtime: client-side
+ * heartbeats and `cancel` notifications get `method_not_found` from the
+ * dispatcher, so disconnect detection silently regresses and per-request
+ * cancel never aborts the matching handler. Catch the mistake at the
+ * surface layer rather than at runtime.
+ */
+export const assert_ws_endpoints_include_protocol_actions = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        const method_names = new Set(ep.methods.map((m) => m.name));
+        for (const expected of PROTOCOL_ACTION_METHODS) {
+            assert.ok(method_names.has(expected), `WS endpoint '${ep.path}' is missing protocol action method '${expected}' — ` +
+                `spread \`protocol_actions\` from 'actions/protocol.js' into \`actions\``);
+        }
+    }
+};
+/**
+ * WS methods follow the kind ⇔ auth biconditional emitted by surface
+ * generation: `kind === 'remote_notification' ⟺ auth === null`.
+ *
+ * `generate_app_surface` produces this shape directly from the action
+ * spec union (notifications carry `auth: null` per `ActionSpecUnion`;
+ * `request_response` carries a `RouteAuth`). The assertion guards against
+ * drift if a future surface emitter, transform, or test fixture violates
+ * it — and gives consumers a clear failure message when a hand-built
+ * surface mocks the shape incorrectly.
+ */
+export const assert_ws_notifications_have_null_auth = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        for (const method of ep.methods) {
+            const is_notification = method.kind === 'remote_notification';
+            const has_null_auth = method.auth === null;
+            assert.ok(is_notification === has_null_auth, `WS method '${method.name}' on endpoint '${ep.path}' violates kind ⇔ auth: ` +
+                `kind='${method.kind}', auth=${has_null_auth ? 'null' : 'non-null'} ` +
+                `(notifications must have auth: null; request_response must have a RouteAuth)`);
+        }
+    }
+};
 /** Default patterns for sensitive REST routes that should be rate-limited. */
 const DEFAULT_SENSITIVE_PATTERNS = [
     /\/login$/,
@@ -424,7 +502,9 @@ export const assert_no_unexpected_public_mutations = (surface, allowlist = []) =
  *
  * Note: RPC endpoints (`create_rpc_endpoint`) use `input: z.null()` on their
  * route specs — the dispatcher handles body/query parsing internally. Real input
- * schemas live in `rpc_endpoints` surface, not on routes.
+ * schemas live in `rpc_endpoints` surface, not on routes; see
+ * `assert_rpc_ws_surface_invariants` for the parallel checks over RPC/WS
+ * method shapes.
  */
 export const assert_mutation_routes_use_post = (surface) => {
     const input_routes = filter_routes_with_input(surface);
@@ -546,6 +626,28 @@ export const assert_surface_invariants = (surface) => {
     assert_error_code_status_consistency(surface);
     assert_404_schemas_use_specific_errors(surface);
 };
+/**
+ * Run all RPC / WS structural invariants. Options-free — applies
+ * universally to the `surface.rpc_endpoints` and `surface.ws_endpoints`
+ * slots produced by `generate_app_surface`.
+ *
+ * Parallel of `assert_surface_invariants` for the non-REST surfaces.
+ * Within-endpoint duplicate method names and the auth-shape biconditional
+ * are already enforced at startup by `compile_action_registry` (see
+ * `actions/CLAUDE.md` §Registry compile) — these assertions cover only
+ * the contract-surface concerns that a runtime registration check
+ * cannot: empty descriptions, missing protocol-action spread on WS
+ * endpoints, and kind ⇔ auth drift on WS methods.
+ *
+ * @throws AssertionError on the first invariant violation; the message
+ *   names the offending endpoint, method, and field.
+ */
+export const assert_rpc_ws_surface_invariants = (surface) => {
+    assert_rpc_method_descriptions_present(surface);
+    assert_ws_method_descriptions_present(surface);
+    assert_ws_endpoints_include_protocol_actions(surface);
+    assert_ws_notifications_have_null_auth(surface);
+};
 /**
  * Run security policy invariants. Configurable with sensible defaults.
  *

package/dist/testing/transports/surface_source.d.ts

@@ -0,0 +1,51 @@
+import '../assert_dev_env.js';
+/**
+ * Discriminated source for the `AppSurface` a suite asserts against.
+ *
+ * In-process callers pass `{kind: 'inline', spec}` — the full
+ * `AppSurfaceSpec` with route closures intact. Cross-process callers
+ * pass `{kind: 'snapshot', path}` — a committed JSON file containing
+ * only the JSON-serializable `AppSurface` shape.
+ *
+ * Backs the suite parameter that previously was `build: () => AppSurfaceSpec`.
+ *
+ * @module
+ */
+import type { AppSurface, AppSurfaceSpec } from '../../http/surface.js';
+/**
+ * Where a suite reads the `AppSurface` from for its assertions.
+ *
+ * Two variants. The `inline` variant carries the full `AppSurfaceSpec`
+ * (with route closures) — the only variant in-process suites can use
+ * for route-iteration tests, since route closures aren't JSON-serializable.
+ * The `snapshot` variant carries a path to a committed JSON file containing
+ * the `AppSurface` shape only — cross-process consumers use this to assert
+ * against a backend that doesn't share TS handler closures.
+ *
+ * No `'fetched'` (live `/api/surface` endpoint) variant: a dead union
+ * case is dead weight and a code-shaped invitation to add a debug
+ * endpoint the design explicitly rejected; committed snapshot is the
+ * contract.
+ */
+export type SurfaceSource = {
+    readonly kind: 'inline';
+    readonly spec: AppSurfaceSpec;
+} | {
+    readonly kind: 'snapshot';
+    readonly path: string;
+};
+/**
+ * Resolve a `SurfaceSource` to the underlying surface shape.
+ *
+ * The `inline` variant returns the full `AppSurfaceSpec` (route closures
+ * available). The `snapshot` variant returns the serialized `AppSurface`
+ * shape only. Asymmetric on purpose — suites that need `route_specs`
+ * (with closures) must use the `inline` variant; suites working on the
+ * `AppSurface` shape work with either.
+ *
+ * @throws Error when called with `{kind: 'snapshot'}` — the snapshot
+ *   variant lands alongside the cross-process transport plumbing.
+ *   No in-process caller exercises this branch today.
+ */
+export declare const resolve_surface_source: (src: SurfaceSource) => Promise<AppSurface | AppSurfaceSpec>;
+//# sourceMappingURL=surface_source.d.ts.map

package/dist/testing/transports/surface_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface_source.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/surface_source.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GACtB;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAC,GACxD;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GAClC,KAAK,aAAa,KAChB,OAAO,CAAC,UAAU,GAAG,cAAc,CAKrC,CAAC"}

package/dist/testing/transports/surface_source.js

@@ -0,0 +1,19 @@
+import '../assert_dev_env.js';
+/**
+ * Resolve a `SurfaceSource` to the underlying surface shape.
+ *
+ * The `inline` variant returns the full `AppSurfaceSpec` (route closures
+ * available). The `snapshot` variant returns the serialized `AppSurface`
+ * shape only. Asymmetric on purpose — suites that need `route_specs`
+ * (with closures) must use the `inline` variant; suites working on the
+ * `AppSurface` shape work with either.
+ *
+ * @throws Error when called with `{kind: 'snapshot'}` — the snapshot
+ *   variant lands alongside the cross-process transport plumbing.
+ *   No in-process caller exercises this branch today.
+ */
+export const resolve_surface_source = async (src) => {
+    if (src.kind === 'inline')
+        return src.spec;
+    throw new Error(`surface_source.kind === 'snapshot' is not yet implemented; lands with cross-process transport plumbing (path=${src.path})`);
+};

package/dist/ui/SurfaceExplorer.svelte

@@ -17,6 +17,7 @@
 		is_plain_authenticated_auth,
 		is_public_auth,
 		is_role_auth,
+		type RouteAuth,
 	} from '../http/auth_shape.js';
 
 	const {surface}: {surface: AppSurface} = $props();
@@ -28,6 +29,13 @@
 
 	const summary = $derived(surface_auth_summary(surface));
 
+	const rpc_method_count = $derived(
+		surface.rpc_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0),
+	);
+	const ws_method_count = $derived(
+		surface.ws_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0),
+	);
+
 	const auth_matches_filter = (
 		auth: AppSurfaceRoute['auth'],
 		filter: (typeof auth_types)[number],
@@ -51,6 +59,8 @@
 	);
 
 	let expanded_event: string | null = $state.raw(null);
+	let expanded_rpc_method: string | null = $state.raw(null);
+	let expanded_ws_method: string | null = $state.raw(null);
 
 	const toggle_route = (key: string): void => {
 		expanded_route = expanded_route === key ? null : key;
@@ -60,7 +70,15 @@
 		expanded_event = expanded_event === method ? null : method;
 	};
 
-	const format_auth = (auth: AppSurfaceRoute['auth']): string => {
+	const toggle_rpc_method = (key: string): void => {
+		expanded_rpc_method = expanded_rpc_method === key ? null : key;
+	};
+
+	const toggle_ws_method = (key: string): void => {
+		expanded_ws_method = expanded_ws_method === key ? null : key;
+	};
+
+	const format_auth = (auth: RouteAuth): string => {
 		if (is_public_auth(auth)) return 'none';
 		if (is_keeper_auth(auth)) return 'keeper';
 		if (is_role_auth(auth)) return `role:${auth.roles!.join('|')}`;
@@ -68,7 +86,7 @@
 		return 'other';
 	};
 
-	const auth_chip_class = (auth: AppSurfaceRoute['auth']): string => {
+	const auth_chip_class = (auth: RouteAuth): string => {
 		if (is_public_auth(auth)) return 'chip color_b';
 		if (is_keeper_auth(auth)) return 'chip color_c';
 		if (is_role_auth(auth)) return 'chip color_d';
@@ -89,6 +107,8 @@
 		{#if role_count > 0}<span class="chip color_d">{role_count} role</span>{/if}
 		{#if summary.keeper > 0}<span class="chip color_c">{summary.keeper} keeper</span>{/if}
 		<span class="chip">{surface.middleware.length} middleware</span>
+		{#if rpc_method_count > 0}<span class="chip">{rpc_method_count} rpc methods</span>{/if}
+		{#if ws_method_count > 0}<span class="chip">{ws_method_count} ws methods</span>{/if}
 		{#if surface.env.length}<span class="chip">{surface.env.length} env</span>{/if}
 		{#if surface.events.length}<span class="chip">{surface.events.length} events</span>{/if}
 		{#if surface.diagnostics.length}{@const warnings = surface.diagnostics.filter(
@@ -283,6 +303,145 @@
 		</div>
 	{/if}
 
+	{#if surface.rpc_endpoints.length}
+		<h3>rpc endpoints</h3>
+		{#each surface.rpc_endpoints as endpoint (endpoint.path)}
+			<div class="row" style:gap="var(--space_sm)" style:align-items="center">
+				<code>{endpoint.path}</code>
+				<span class="chip">{endpoint.methods.length} methods</span>
+			</div>
+			{#if endpoint.methods.length === 0}
+				<p class="text_50">no methods</p>
+			{:else}
+				<div style:overflow-x="auto">
+					<table>
+						<thead>
+							<tr>
+								<th>method</th>
+								<th>auth</th>
+								<th>side effects</th>
+								<th>rate limit</th>
+								<th>description</th>
+							</tr>
+						</thead>
+						<tbody>
+							{#each endpoint.methods as method (method.name)}
+								{@const key = `${endpoint.path}|${method.name}`}
+								<tr onclick={() => toggle_rpc_method(key)} style:cursor="pointer">
+									<td><code>{method.name}</code></td>
+									<td>
+										<span class={auth_chip_class(method.auth)}>{format_auth(method.auth)}</span>
+									</td>
+									<td>{method.side_effects ? 'yes' : 'no'}</td>
+									<td class="text_50">{method.rate_limit_key ?? '-'}</td>
+									<td class="text_50">{method.description}</td>
+								</tr>
+								{#if expanded_rpc_method === key}
+									<tr transition:slide>
+										<td colspan="5">
+											<div class="column" style:gap="var(--space_sm)">
+												<div>
+													<strong>input</strong>
+													{#if method.input_schema}
+														<pre>{JSON.stringify(method.input_schema, null, 2)}</pre>
+													{:else}
+														<span class="text_50">none (z.void)</span>
+													{/if}
+												</div>
+												<div>
+													<strong>output</strong>
+													<pre>{JSON.stringify(method.output_schema, null, 2)}</pre>
+												</div>
+											</div>
+										</td>
+									</tr>
+								{/if}
+							{/each}
+						</tbody>
+					</table>
+				</div>
+			{/if}
+		{/each}
+	{/if}
+
+	{#if surface.ws_endpoints.length}
+		<h3>websocket endpoints</h3>
+		{#each surface.ws_endpoints as endpoint (endpoint.path)}
+			<div
+				class="row"
+				style:gap="var(--space_sm)"
+				style:align-items="center"
+				style:flex-wrap="wrap"
+			>
+				<code>{endpoint.path}</code>
+				<span class="chip">{endpoint.methods.length} methods</span>
+				{#each endpoint.required_roles as role (role)}
+					<span class="chip color_d">role:{role}</span>
+				{/each}
+				{#each endpoint.allowed_origins as origin (origin)}
+					<span class="chip color_b"><code>{origin}</code></span>
+				{/each}
+			</div>
+			{#if endpoint.methods.length === 0}
+				<p class="text_50">no methods</p>
+			{:else}
+				<div style:overflow-x="auto">
+					<table>
+						<thead>
+							<tr>
+								<th>method</th>
+								<th>kind</th>
+								<th>auth</th>
+								<th>side effects</th>
+								<th>rate limit</th>
+								<th>description</th>
+							</tr>
+						</thead>
+						<tbody>
+							{#each endpoint.methods as method (method.name)}
+								{@const key = `${endpoint.path}|${method.name}`}
+								<tr onclick={() => toggle_ws_method(key)} style:cursor="pointer">
+									<td><code>{method.name}</code></td>
+									<td><span class="chip">{method.kind}</span></td>
+									<td>
+										{#if method.auth}
+											<span class={auth_chip_class(method.auth)}>{format_auth(method.auth)}</span>
+										{:else}
+											<span class="text_50">—</span>
+										{/if}
+									</td>
+									<td>{method.side_effects ? 'yes' : 'no'}</td>
+									<td class="text_50">{method.rate_limit_key ?? '-'}</td>
+									<td class="text_50">{method.description}</td>
+								</tr>
+								{#if expanded_ws_method === key}
+									<tr transition:slide>
+										<td colspan="6">
+											<div class="column" style:gap="var(--space_sm)">
+												<div>
+													<strong>input</strong>
+													{#if method.input_schema}
+														<pre>{JSON.stringify(method.input_schema, null, 2)}</pre>
+													{:else}
+														<span class="text_50">none (z.void)</span>
+													{/if}
+												</div>
+												<div>
+													<strong>output</strong>
+													<pre>{JSON.stringify(method.output_schema, null, 2)}</pre>
+												</div>
+											</div>
+										</td>
+									</tr>
+								{/if}
+							{/each}
+						</tbody>
+					</table>
+				</div>
+			{/if}
+		{/each}
+	{/if}
+
 	{#if surface.diagnostics.length}
 		<h3>diagnostics</h3>
 		<div style:overflow-x="auto">

package/dist/ui/SurfaceExplorer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SurfaceExplorer.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/SurfaceExplorer.svelte"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,UAAU,EAAwC,MAAM,oBAAoB,CAAC;AASzF,KAAK,gBAAgB,GAAI;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAuShD,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"SurfaceExplorer.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/SurfaceExplorer.svelte"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,UAAU,EAAwC,MAAM,oBAAoB,CAAC;AAUzF,KAAK,gBAAgB,GAAI;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAgchD,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -46,11 +46,11 @@
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.59.0",
     "@fuzdev/fuz_ui": "^0.192.0",
-    "@fuzdev/fuz_util": "^0.59.0",
+    "@fuzdev/fuz_util": "^0.60.1",
     "@fuzdev/gro": "^0.199.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@node-rs/argon2": "^2.0.2",
-    "@ryanatkn/eslint-config": "^0.11.0",
+    "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.55.0",
@@ -62,7 +62,7 @@
     "eslint": "^9.39.4",
     "eslint-plugin-svelte": "^3.15.1",
     "esm-env": "^1.2.2",
-    "hono": "^4.12.7",
+    "hono": "^4.12.21",
     "jsdom": "^28.1.0",
     "magic-string": "^0.30.21",
     "pg": "^8.20.0",