From c84df29834c955b87ab4a468343ac4c4eb70e028 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 06:45:36 +0000 Subject: [PATCH] docs(api): record the os:check decision for client-sdk.mdx, and fence its JSX as tsx The page has 13 TypeScript fences and 0 os:check markers. Marking them was measured rather than assumed: all 13 marked at once produce 128 diagnostics and not one is a doc-vs-SDK divergence. Two structural reasons, neither fixable on this page: - content/docs/** belongs to check:skill-examples' "skills + docs" surface, whose paths map derives from @objectstack/spec alone, and spec does not depend on @objectstack/client. Every fence importing the SDK reds TS2307. - The remaining fences are deliberate continuation fragments sharing the Quick Start's `client`, so they red TS2304. Making either class compile would mean hand-declaring the SDK's own types or injecting casts into prose whose subject is the real API. Also retags the React Hooks block tsx (it is JSX). The gate writes each block out with its fence's extension, so as `typescript` a marker on it produced only TS1xxx syntax errors -- and tsc never runs the semantic pass after those, which suppressed type-checking for every marked block across skills/ and content/docs/ (measured: 128 semantic diagnostics collapse to 0). check:doc-authoring accepts tsx, so the block stays visible to it. Part of #11942 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01UjM2ia8Av1v5NqfqQEQmC6 --- content/docs/api/client-sdk.mdx | 37 ++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx index 42a0a12ff7..dd20c154a9 100644 --- a/content/docs/api/client-sdk.mdx +++ b/content/docs/api/client-sdk.mdx @@ -25,6 +25,41 @@ The `@objectstack/client` is the official TypeScript client for ObjectStack. It pnpm add @objectstack/client ``` +{/* + CONTRIBUTOR NOTE — none of this page's TypeScript fences carries an + `os:check` marker, and that is a recorded decision rather than an omission. + + `check:skill-examples` compiles marked blocks per SURFACE. `content/docs/**` + belongs to the "skills + docs" surface, whose resolution dir and `paths` map + are derived from `@objectstack/spec` alone — and `@objectstack/spec` does not + depend on `@objectstack/client`. So a marker on any fence that imports the SDK + reds with TS2307 "Cannot find module '@objectstack/client'" — a + surface-resolution gap, not doc-vs-SDK drift. + + Every other fence is a deliberate continuation fragment: Quick Start + establishes `client` once and each later block continues that implied context, + so a marker there reds with TS2304 "Cannot find name 'client'". Making either + class compile would mean hand-declaring the SDK's own types, or injecting + casts into prose whose subject IS the real API — pinning each example to + itself and teaching worse code than the page teaches now. + + Measured on this page (all 13 fences marked, then reverted): 128 diagnostics, + every one TS2307 / TS2304 / TS18004 / TS18046 / TS2591 / TS7006 / TS7026 / + TS2875. Not one was a doc-vs-SDK divergence. + + The React Hooks block near the end is fenced tsx, not typescript, because it + IS JSX: the gate writes every block out with its fence's own extension, and + JSX in a .ts file is a syntax error. That reaches past this page — tsc stops + at syntax errors and never runs the semantic pass, so one such block would + suppress type-checking for every marked block across skills/ and + content/docs/ (measured here: 128 semantic diagnostics collapse to 0). Please + do not retag it back. + + The marker becomes worth adding here the day the docs surface can resolve + `@objectstack/client` — the same condition recorded in + content/docs/kernel/runtime-services/data-service.mdx. +*/} + ## Quick Start ```typescript @@ -636,7 +671,7 @@ For React applications, use `@objectstack/client-react`: pnpm add @objectstack/client-react ``` -```typescript +```tsx import { ObjectStackProvider, useClient, useQuery } from '@objectstack/client-react'; import { ObjectStackClient } from '@objectstack/client';