docs: update zod and svelte patterns

Author: ryanatkn

skills/fuz-stack/references/svelte-patterns.md

@@ -46,7 +46,7 @@ non-zero). Use `$state.raw()` unless you have a specific reason not to.
 ```typescript
 // $state.raw() - the default for all types
 let name = $state.raw(''); // primitive — no difference in behavior
-let ollama_response = $state.raw<OllamaShowResponse | null>(null); // object replaced wholesale
+let api_response = $state.raw<ApiResponse | null>(null); // object replaced wholesale
 let selections: ReadonlyArray<Item> = $state.raw([]); // array replaced wholesale
 
 // $state() - opt-in for arrays/objects mutated in place

skills/fuz-stack/references/zod-schemas.md

@@ -23,21 +23,24 @@ defaults, metadata, CLI help text, and serialization.
 | Foundation | `@fuzdev/fuz_util/zod.ts` | Schema introspection — extract descriptions, defaults, aliases, types, properties; unwrap wrappers; check optional/nullable/default; format values for display |
 | Cell helpers | `@fuzdev/zzz/zod_helpers.ts` | `Uuid`, `Datetime` branded types and factories; schema unwrapping; field extraction; validation error formatting |
 | CLI | `@fuzdev/fuz_app/cli/args.ts`, `help.ts` | Schema-validated CLI arg parsing; schema-driven help text generation |
-| HTTP | `@fuzdev/fuz_app/http/schema_helpers.ts` | `schema_to_surface()` exports JSON Schema via `z.toJSONSchema()` for snapshot-testable API surfaces |
+| HTTP | `@fuzdev/fuz_app/http/schema_helpers.ts` | `schema_to_surface()` exports JSON Schema via `z.toJSONSchema()` for snapshot-testable API surfaces; `instanceof` checks for schema type detection |
 | Testing | `@fuzdev/fuz_app/testing/schema_generators.ts` | Schema-driven test data generation — valid bodies, adversarial inputs |
 
 ## Core Conventions
 
 1. **`z.strictObject()`** — default for all object schemas, including inside
    `z.discriminatedUnion()` and `z.union()`. Rejects unknown keys.
-   **Exception**: external data (`z.looseObject()` or `z.object()` with
-   comment explaining why).
+   **Exceptions**: external data (`z.looseObject()` or `z.object()` with
+   comment explaining why); response/error schemas consumed by clients
+   (`z.looseObject()` — allows adding fields without breaking consumers).
 2. **PascalCase naming** — schema and inferred type share the same name.
 3. **`.meta({description: '...'})`** — not `.describe()`. `.meta()` supports
    additional keys (`aliases`, `sensitivity`).
 4. **`safeParse` at boundaries** — graceful errors for external input (HTTP
-   requests, API responses). `parse` for internal assertions, config loading,
-   CLI args, and factory functions where failure is fatal.
+   requests, API responses). `parse` for internal assertions, CLI args, and
+   factory functions where failure is fatal. `safeParse` + custom throw when
+   you need better error context than `parse` provides (e.g., env loading).
+   `safeParse` + return null for optional config files that may be absent.
 
 ### The Canonical Pattern
 
@@ -73,6 +76,11 @@ const PackageJson = z.looseObject({name: z.string(), version: z.string()});
 // z.object: parses external GitHub API responses
 const GithubPullRequest = z.object({number: z.number(), title: z.string()});
 
+// OK: z.looseObject for response/error schemas — clients tolerate additions
+// z.looseObject: error responses may carry extra context fields
+const ApiError = z.looseObject({error: z.string()});
+const TableListOutput = z.looseObject({tables: z.array(z.strictObject({name: z.string()}))});
+
 // WRONG: .describe() — works but not the convention
 const Bar = z.string().describe('a bar');
 
@@ -97,6 +105,10 @@ Schemas with `.default()` or `.transform()` have different input and output
 types. `z.infer<>` gives the output (post-parse) type. `z.input<>` gives the
 pre-parse type — what callers provide before defaults are applied.
 
+Export `z.input<>` when callers construct partial instances via `.parse()` —
+Cell instantiation, resource builders, config files. Skip it when the schema
+is only consumed internally (env loading, action spec `satisfies`).
+
 This is a **systematic pattern** in zzz and tx:
 
 ```typescript
@@ -212,6 +224,18 @@ email: Email.nullish(),  // fuz_app invite creation
 before: PackageCurrent.nullable().catch(null),  // tx change schemas
 ```
 
+## Field-Level Validation
+
+Use `.shape` to validate individual fields without parsing the whole object:
+
+```typescript
+// zzz — validate a single field value
+ProviderJson.shape.name.parse(value);
+
+// zzz/socket.svelte.ts — Cell field mutations via shape access
+SocketJson.shape.url.parse(new_url);
+```
+
 ## Transform Pipelines
 
 ```typescript
@@ -403,8 +427,8 @@ if (!result.success) {
 }
 c.set('validated_input', result.data);
 
-// zzz/ollama.svelte.ts — external API responses
-const parsed = OllamaListResponse.safeParse(response);
+// zzz — external API responses
+const parsed = ApiResponse.safeParse(response);
 ```
 
 Route specs declare input/output schemas for auto-generated validation
@@ -416,12 +440,31 @@ Use `parse` when invalid data means a bug or fatal misconfiguration:
 
 ```typescript
 RoleName.parse(name);                                    // internal assertion
-return TxOptions.parse(raw);                             // config loading
 const args = RunApplyArgs.parse(raw_args);               // CLI args
 return PackageResource.parse({type: 'package', ...config}); // factory function
 const parsed = this.schema.parse(v);                     // Cell field update
 ```
 
+### safeParse with Custom Error Handling
+
+`safeParse` + custom throw gives better error context than bare `parse`.
+`safeParse` + return null handles optional data that may be absent or invalid:
+
+```typescript
+// fuz_app/env/load.ts — env loading: safeParse + custom error with raw values
+const result = schema.safeParse(raw);
+if (!result.success) {
+	throw new EnvValidationError(raw, result.error);
+}
+
+// fuz_app/cli/config.ts — optional config file: safeParse + return null
+const result = schema.safeParse(parsed);
+if (!result.success) {
+	runtime.warn(`Invalid config.json: ${result.error.message}`);
+	return null;
+}
+```
+
 ### Formatting Errors
 
 ```typescript
@@ -444,6 +487,7 @@ export const format_zod_validation_error = (error: z.ZodError): string =>
 |-----------|---------|-------|
 | Object schemas (internal) | `z.strictObject({...})` | `z.object({...})` |
 | Object schemas (external data) | `z.looseObject({...})` or `z.object({...})` with comment | `z.strictObject({...})` |
+| Response/error schemas | `z.looseObject({...})` — tolerates added fields | `z.strictObject({...})` |
 | Discriminated union members | `z.strictObject({type: z.literal('a'), ...})` | `z.object({type: z.literal('a'), ...})` |
 | Descriptions | `.meta({description: '...'})` | `.describe('...')` |
 | Schema naming | `const MyThing = z.strictObject(...)` | `const my_thing`, `const MyThingSchema` |

src/routes/libraries.json

@@ -48405,14 +48405,14 @@
 				"@fuzdev/fuz_code": "^0.45.1",
 				"@fuzdev/fuz_css": "^0.58.0",
 				"@fuzdev/fuz_mastodon": "^0.39.0",
-				"@fuzdev/fuz_ui": "^0.191.3",
+				"@fuzdev/fuz_ui": "^0.191.4",
 				"@fuzdev/fuz_util": "^0.55.0",
-				"@fuzdev/gro": "^0.197.2",
+				"@fuzdev/gro": "^0.197.3",
 				"@jridgewell/trace-mapping": "^0.3.31",
 				"@ryanatkn/eslint-config": "^0.10.1",
 				"@sveltejs/acorn-typescript": "^1.0.9",
 				"@sveltejs/adapter-static": "^3.0.10",
-				"@sveltejs/kit": "^2.55.0",
+				"@sveltejs/kit": "^2.57.0",
 				"@sveltejs/package": "^2.5.7",
 				"@sveltejs/vite-plugin-svelte": "^6.2.4",
 				"@types/estree": "^1.0.8",
@@ -48425,7 +48425,7 @@
 				"magic-string": "^0.30.21",
 				"prettier": "^3.7.4",
 				"prettier-plugin-svelte": "^3.5.1",
-				"svelte": "^5.55.0",
+				"svelte": "^5.55.2",
 				"svelte-check": "^4.4.5",
 				"svelte2tsx": "^0.7.52",
 				"tslib": "^2.8.1",
@@ -50198,14 +50198,14 @@
 				"@changesets/changelog-git": "^0.2.1",
 				"@fuzdev/fuz_code": "^0.45.1",
 				"@fuzdev/fuz_css": "^0.58.0",
-				"@fuzdev/fuz_ui": "^0.191.3",
+				"@fuzdev/fuz_ui": "^0.191.4",
 				"@fuzdev/fuz_util": "^0.55.0",
-				"@fuzdev/gro": "^0.197.2",
+				"@fuzdev/gro": "^0.197.3",
 				"@jridgewell/trace-mapping": "^0.3.31",
 				"@ryanatkn/eslint-config": "^0.10.1",
 				"@sveltejs/acorn-typescript": "^1.0.9",
 				"@sveltejs/adapter-static": "^3.0.10",
-				"@sveltejs/kit": "^2.55.0",
+				"@sveltejs/kit": "^2.57.0",
 				"@sveltejs/package": "^2.5.7",
 				"@sveltejs/vite-plugin-svelte": "^6.2.4",
 				"@types/estree": "^1.0.8",
@@ -50217,7 +50217,7 @@
 				"magic-string": "^0.30.21",
 				"prettier": "^3.7.4",
 				"prettier-plugin-svelte": "^3.5.1",
-				"svelte": "^5.55.0",
+				"svelte": "^5.55.2",
 				"svelte-check": "^4.4.5",
 				"svelte2tsx": "^0.7.52",
 				"tslib": "^2.8.1",
@@ -54977,16 +54977,16 @@
 			},
 			"devDependencies": {
 				"@changesets/changelog-git": "^0.2.1",
-				"@fuzdev/fuz_app": "^0.3.3",
+				"@fuzdev/fuz_app": "^0.4.0",
 				"@fuzdev/fuz_code": "^0.45.1",
 				"@fuzdev/fuz_css": "^0.58.0",
-				"@fuzdev/fuz_ui": "^0.191.3",
+				"@fuzdev/fuz_ui": "^0.191.4",
 				"@fuzdev/fuz_util": "^0.55.0",
 				"@jridgewell/trace-mapping": "^0.3.31",
 				"@ryanatkn/eslint-config": "^0.10.1",
 				"@sveltejs/acorn-typescript": "^1.0.9",
 				"@sveltejs/adapter-static": "^3.0.10",
-				"@sveltejs/kit": "^2.55.0",
+				"@sveltejs/kit": "^2.57.0",
 				"@sveltejs/vite-plugin-svelte": "^6.2.4",
 				"@types/deno": "^2.5.0",
 				"@types/estree": "^1.0.8",
@@ -54999,7 +54999,7 @@
 				"ollama": "^0.6.3",
 				"prettier": "^3.7.4",
 				"prettier-plugin-svelte": "^3.4.1",
-				"svelte": "^5.55.0",
+				"svelte": "^5.55.2",
 				"svelte-check": "^4.4.5",
 				"svelte2tsx": "^0.7.52",
 				"tslib": "^2.8.1",