@tristan2828/ui-foundation 4.21.0 → 4.23.0

package/conventions/docs/add-an-entity.md

@@ -642,3 +642,26 @@ soft one; copy it.
 - **Hard-deleted:** `DELETE` removes the row. Give the entity no `delete`
   in `mcp_entities.py`: a chat that read planted instructions would
   destroy data that only a backup returns.
+
+## Fields only a script writes
+
+Some fields the API takes on create and update are for a script, not for
+the people or chats using the app: an importer that runs again and again
+stores each record's id in the source it came from, so a re-run finds the
+record even after it's renamed. The API has to accept that id, for the
+importer. A chat that changed or cleared it would break the matching, and
+the next run would create the record a second time.
+
+- *MCP:* list the field's wire name in the entity's `McpEntity`
+  `script_only` (`script_only=("sourceId",)`). Chats still read it
+  (`fetch` shows it), but `create` and `update` refuse a call that names
+  it, by its wire name or its snake_case one, before the entity's own
+  function runs: `Nothing was saved.` and `- sourceId: set by a script,
+  not through MCP`, with no audit row. It's left out of the two tools'
+  descriptions, so a chat isn't invited to send it. The backend refuses
+  to start if a name isn't a field of the create or update schema, or if
+  create requires it (a chat could then never create one).
+- *Screens:* the form leaves the field out, for the same reason.
+- Don't use it for a field the server works out itself (`computed`) or
+  one that's never on the request: those aren't in the create or update
+  schema to begin with.

package/conventions/docs/timed-screens.md

@@ -10,6 +10,7 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 | `useSessionClock` | A clock that doesn't drift, with pause and resume: `idle`, `running`, `done` |
 | `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
 | `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` | Sound cues with no audio files |
+| `canVibrate` | Whether this browser can vibrate, to offer a Vibrate setting only where it works |
 | `useMuted` | A mute toggle remembered on this device |
 | `usePrefersReducedMotion` | Whether to swap movement for a fade |
 
@@ -95,6 +96,13 @@ Browsers block sound until the person has clicked or tapped. So:
   line still being spoken. `hush()` stops it. Call `hush()` when the
   session stops or the view closes.
 - `vibrate(pattern)` only works on Android. Elsewhere it does nothing.
+- **A Vibrate setting is offered only where `canVibrate()` is true.**
+  iPhone browsers can't vibrate, so a toggle there would set something
+  that does nothing. `canVibrate()` is the same test `vibrate()` makes, so
+  the two never disagree. Read it once, since it doesn't change during a
+  session: `const [vibrates] = useState(canVibrate)`. Show the toggle (a
+  pressed button named "Vibrate", like Mute) only when `vibrates` is
+  true, and check the setting before each `vibrate()` call.
 - Every one of them is a no-op where the browser can't make the sound, so
   none needs a check around it.
 - **Mute** is the app's: `const [muted, setMuted] = useMuted('my-app:routine:muted')`,
@@ -159,18 +167,18 @@ test('running, paused and done', async ({ page }) => {
 steps, so every reading picks up however long the machine took since the
 last `fastForward`. A count-up with no end (a stopwatch, a hold that
 ends on a tap) has nothing to stop at, so under load its readings are
-off by a second or more. Pause the clock once the session opens and
-move it only with `fastForward`:
+off by a second or more. Pause the clock before the session starts, at a
+time fixed from the install, and move it only with `fastForward`:
 
 ```ts
 test('the hold counts up until the tap', async ({ page }) => {
-  await page.clock.install()
+  const t0 = Date.now()
+  await page.clock.install({ time: t0 })
   await page.goto('/routine')
+  // The page's clock runs no faster than real time, so a minute on is still
+  // ahead for the whole test timeout; nothing on the start screen is timed.
+  await page.clock.pauseAt(t0 + 60_000)
   await page.getByRole('button', { name: 'Start' }).click()
-  // Slightly ahead, never Date.now() itself: the page's clock has already
-  // moved past the test's, and pauseAt() refuses an earlier time with
-  // "Cannot fast-forward to the past".
-  await page.clock.pauseAt(Date.now() + 50)
 
   await page.clock.fastForward('00:42')
   await expect(page.getByRole('timer', { name: 'Held for' })).toHaveText('0:42')
@@ -183,10 +191,12 @@ test('the hold counts up until the tap', async ({ page }) => {
 })
 ```
 
-- **`pauseAt(Date.now() + 50)`, not `pauseAt(Date.now())`.** The page's
-  fake time is already a little ahead of the test's `Date.now()`, and
-  `pauseAt` fast-forwards to the time it's given, so a time already
-  passed fails with "Cannot fast-forward to the past".
+- **Pause at a time fixed from `install`, before the session starts.**
+  Never at one read after it (`pauseAt(Date.now() + 50)` after Start):
+  until the pause lands the page's fake clock runs in real time, so a
+  slow round trip or a busy first frame puts it past that time, and
+  `pauseAt` fails with "Cannot fast-forward to the past". A time a minute
+  on from `install` is still ahead however slow the machine is.
 - **`clock.resume()` before axe or closing the view.** With the clock
   paused, axe's scan never finishes and the dialog's close animation
   never ends, so the test times out with nothing pointing at the clock.

package/dist/index.d.ts

@@ -55,4 +55,4 @@ export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, type PushController, type PushControllerOptions, type PushEnvironment, type PushPermission, type PushStatus, } from './hooks/use-push-permission.js';
 export { cn } from './lib/utils.js';
-export { chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';
+export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';

package/dist/index.js

@@ -61,4 +61,4 @@ export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
-export { chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';
+export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';

package/dist/lib/audio-cues.d.ts

@@ -38,6 +38,13 @@ export type AudioCues = {
     vibrate: (pattern: number | number[]) => void;
 };
 export declare function createAudioCues(env: AudioCuesEnvironment): AudioCues;
+/**
+ * Whether this browser can vibrate: Android browsers can, iPhone browsers
+ * can't. The same test vibrate() makes, so a Vibrate setting offered only
+ * where this is true never sets something that does nothing. Read it once;
+ * it doesn't change during a session.
+ */
+export declare function canVibrate(): boolean;
 /** Call from the click or tap that starts a session; sound is allowed from then on. */
 export declare const unlockAudio: AudioCues['unlockAudio'];
 /** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */

package/dist/lib/audio-cues.js

@@ -109,6 +109,15 @@ export function createAudioCues(env) {
         },
     };
 }
+/**
+ * Whether this browser can vibrate: Android browsers can, iPhone browsers
+ * can't. The same test vibrate() makes, so a Vibrate setting offered only
+ * where this is true never sets something that does nothing. Read it once;
+ * it doesn't change during a session.
+ */
+export function canVibrate() {
+    return typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
+}
 let shared = null;
 function browserCues() {
     if (shared)
@@ -118,9 +127,7 @@ function browserCues() {
         AudioContext: win?.AudioContext ?? win?.webkitAudioContext,
         speechSynthesis: win?.speechSynthesis,
         SpeechSynthesisUtterance: win?.SpeechSynthesisUtterance,
-        vibrate: typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function'
-            ? (pattern) => navigator.vibrate(pattern)
-            : undefined,
+        vibrate: canVibrate() ? (pattern) => navigator.vibrate(pattern) : undefined,
     });
     return shared;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.21.0",
+  "version": "4.23.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {