@flickfyi/flkr 0.0.140 → 0.0.146

package/node_modules/@flickfyi/core/src/kowalski/use-clock.ts

@@ -0,0 +1,19 @@
+import { useLayoutEffect, useState } from 'react'
+
+/**
+ * Wall time is recomputed after suspension; interval counts are never persisted. Activation,
+ * or a change of `key`, refreshes before paint, so a clock never shows a stale time when it
+ * switches on or when what it measures (such as a timer's end) changes.
+ */
+export function useClock(active = true, key?: string) {
+	const [now, setNow] = useState(Date.now)
+	useLayoutEffect(() => {
+		if (!active) {
+			return
+		}
+		setNow(Date.now())
+		const handle = setInterval(() => setNow(Date.now()), 1000)
+		return () => clearInterval(handle)
+	}, [active, key])
+	return now
+}

package/node_modules/@flickfyi/core/src/kowalski/use-configured-feature.ts

@@ -0,0 +1,85 @@
+import { useEffect, useMemo } from 'react'
+import type { z } from 'zod/v4'
+
+import { useFeatureStore } from './use-feature-store'
+
+/** Authored seeds change only at a newer manifest revision; live values otherwise win. */
+export function useConfiguredFeature<
+	T extends { configuration: unknown; configurationRevision: number },
+>({
+	name,
+	revision,
+	schema,
+	scope,
+	seed,
+}: {
+	name: string
+	revision: number
+	schema: z.ZodType<T>
+	scope: 'private' | 'public'
+	seed: T
+}) {
+	const configuration = JSON.stringify(seed)
+	const store = useFeatureStore({
+		initialState: { ...seed, configuration: seed, configurationRevision: revision },
+		name,
+		schema,
+		scope,
+	})
+	const { ready, set, value } = store
+	const current = JSON.stringify(value)
+	const attempted = useMemo<{ key?: string }>(() => ({}), [name, schema, scope])
+	const update = useMemo(() => {
+		if (!ready || revision <= value.configurationRevision) {
+			return {}
+		}
+		try {
+			const baseline = schema.parse(value.configuration ?? {})
+			const patch: Partial<T> = {}
+			for (const key in seed) {
+				if (
+					key !== 'configuration' &&
+					key !== 'configurationRevision' &&
+					JSON.stringify(seed[key]) !== JSON.stringify(baseline[key])
+				) {
+					patch[key] = seed[key]
+				}
+			}
+			const candidate = { ...patch, configuration: seed, configurationRevision: revision }
+			if (!schema.safeParse({ ...value, ...candidate }).success) {
+				return {
+					error:
+						'The requested update conflicts with your saved values. Adjust the related fields to apply it.',
+				}
+			}
+			return { patch: candidate }
+		} catch {
+			return {
+				error:
+					'The saved configuration could not be read. Your current values are preserved.',
+			}
+		}
+		// Serialized data makes equivalent renders stable, including a failed save.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [configuration, current, ready, revision, schema])
+	useEffect(() => {
+		const key = JSON.stringify([configuration, current, revision])
+		if (!update.patch || attempted.key === key) {
+			return
+		}
+		attempted.key = key
+		set(update.patch)
+	}, [attempted, configuration, current, revision, set, update])
+	const retryPatch = update.patch
+	return {
+		...store,
+		error: update.error ?? store.error,
+		retry:
+			store.retry ??
+			(store.error && !store.saving && retryPatch
+				? () => {
+						set(retryPatch)
+					}
+				: undefined),
+	}
+}

package/node_modules/@flickfyi/core/src/kowalski/use-feature-store.ts

@@ -0,0 +1,119 @@
+import { makeLens } from '@flickfyi/lens'
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+import { z } from 'zod/v4'
+
+import { createQuantumStoreAdapter } from '~/quantum/use-store'
+
+/** Wait for authoritative Quantum data; writes are optimistic only after hydration. */
+export function useFeatureStore<T extends object>({
+	initialState,
+	name,
+	schema,
+	scope = 'private',
+}: {
+	initialState: T
+	name: string
+	schema: z.ZodType<T>
+	scope?: 'private' | 'public'
+}) {
+	const lens = useMemo(() => makeLens({ schema }), [schema])
+	const writes = useMemo<{ pending: Set<Partial<T>>; error?: string }>(
+		() => ({ pending: new Set() }),
+		[lens, name, scope]
+	)
+	const adapter = useMemo(
+		() => {
+			const adapter = createQuantumStoreAdapter<FeatureSnapshot<T>>(
+				async () =>
+					Quantum.openStore({ initialState, name, scope, version: lens.latest }),
+				{ ready: false, value: initialState },
+				async raw => {
+					const value = await lens.parse(raw.rawValue, {
+						from: z.literal(lens.latest).parse(raw.version),
+					})
+					return { ready: true, value }
+				},
+				() =>
+					adapter.replaceSnapshot({
+						...adapter.getSnapshot(),
+						loadFailed: true,
+						ready: false,
+					})
+			)
+			return adapter
+		},
+		// Initial values seed a newly created store, never replace an existing one.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[lens, name, scope, writes]
+	)
+	const snapshot = useSyncExternalStore(
+		adapter.subscribe,
+		adapter.getSnapshot,
+		adapter.getSnapshot
+	)
+	const set = useCallback(
+		(update: Partial<T> | ((current: T) => Partial<T>), onSaved?: () => void) => {
+			const current = adapter.getSnapshot()
+			const native = adapter.getStore()
+			const commit = native?.setAsync
+			if (!current.ready || !native || !commit || native.canWrite === false) {
+				return false
+			}
+			const visible = overlay(current.value, writes.pending)
+			const patch = typeof update === 'function' ? update(visible) : update
+			schema.parse({ ...visible, ...patch })
+			writes.pending.add(patch)
+			writes.error = undefined
+			adapter.replaceSnapshot({ ...current })
+			void (async () => {
+				try {
+					const raw = await commit.call(native, patch)
+					if (adapter.getStore() === native) {
+						await adapter.acceptSnapshot(raw)
+						onSaved?.()
+					}
+				} catch {
+					writes.error = 'Could not save this change. Please try again.'
+				} finally {
+					writes.pending.delete(patch)
+					adapter.replaceSnapshot({ ...adapter.getSnapshot() })
+				}
+			})()
+			return true
+		},
+		[adapter, schema, writes]
+	)
+	const retry = useCallback(() => {
+		adapter.replaceSnapshot({ ...adapter.getSnapshot(), loadFailed: false, ready: false })
+		adapter.retry()
+	}, [adapter])
+	const supported = adapter.getStore()?.setAsync !== undefined
+	const writable = adapter.getStore()?.canWrite !== false
+	return {
+		error: snapshot.loadFailed
+			? 'Could not load this feature. Please try again.'
+			: snapshot.ready && !supported
+				? 'Update Flick to save changes to this feature.'
+				: writable
+					? writes.error
+					: 'This view is read-only.',
+		ready: snapshot.ready && supported && writable,
+		retry: snapshot.loadFailed ? retry : undefined,
+		saving: writes.pending.size > 0,
+		set,
+		value: overlay(snapshot.value, writes.pending),
+	}
+}
+
+type FeatureSnapshot<T> = {
+	loadFailed?: boolean
+	ready: boolean
+	value: T
+}
+
+function overlay<T>(value: T, pending: Set<Partial<T>>) {
+	for (const patch of pending) {
+		value = { ...value, ...patch }
+	}
+	return value
+}

package/node_modules/@flickfyi/core/src/molecules/field/field.tsx

@@ -0,0 +1,34 @@
+import { Flex, Text } from '@flickfyi/core'
+import * as stylex from '@stylexjs/stylex'
+import type { PropsWithChildren, ReactNode } from 'react'
+
+import { space } from '~/themes/scale.stylex'
+import { roles } from '~/themes/shared'
+import { colors } from '~/themes/tokens.stylex'
+
+/** One labelled control: the label above, the control, and its error below. */
+export function Field({
+	children,
+	error,
+	label,
+	style,
+}: PropsWithChildren<{
+	error?: ReactNode
+	label: string
+	style?: stylex.StyleXArray<stylex.StyleXStyles>
+}>) {
+	return (
+		<Flex {...stylex.props(styles.root, style)}>
+			<Text {...stylex.props(roles.label, styles.label)}>{label}</Text>
+			{children}
+			{error && <Text {...stylex.props(roles.muted, styles.error)}>{error}</Text>}
+		</Flex>
+	)
+}
+
+// The label reads like a Card header label: muted, in the theme's label case.
+const styles = stylex.create({
+	error: { color: colors.danger },
+	label: { color: colors.muted },
+	root: { alignItems: 'stretch', gap: space[2], minWidth: 0 },
+})

package/node_modules/@flickfyi/core/src/molecules/index.ts

@@ -1,6 +1,9 @@
 export { Card } from './card/card'
 export { Choice, completedTaskStyle } from './choice/choice'
+export { Field } from './field/field'
 export { List } from './list/list'
 export { Progress } from './progress/progress'
 export { QuantityGroup } from './quantity-group/quantity-group'
+export { Segmented } from './segmented/segmented'
 export { Stat } from './stat/stat'
+export { Stepper } from './stepper/stepper'

package/node_modules/@flickfyi/core/src/molecules/segmented/segmented.tsx

@@ -0,0 +1,48 @@
+import { Flex, Text } from '@flickfyi/core'
+import * as stylex from '@stylexjs/stylex'
+
+import { Button } from '~/atoms/button/button'
+import { space } from '~/themes/scale.stylex'
+import { button } from '~/themes/shared'
+
+/** Pick one of a few options; the chosen one wears the theme's selected paint. */
+export function Segmented<Value extends number | string>({
+	disabled = false,
+	onChange,
+	options,
+	value,
+}: {
+	disabled?: boolean
+	onChange: (value: Value) => void
+	options: ReadonlyArray<{ label: string; value: Value }>
+	value: Value | undefined
+}) {
+	return (
+		<Flex {...stylex.props(styles.root)}>
+			{options.map(option => (
+				<Button
+					disabled={disabled}
+					key={String(option.value)}
+					onClick={() => onChange(option.value)}
+					selected={option.value === value}
+					style={[button.secondary, styles.segment]}
+				>
+					<Text>{option.label}</Text>
+				</Button>
+			))}
+		</Flex>
+	)
+}
+
+// Equal segments with gap-2. A segment never shrinks below its label, so a row
+// that runs out of room wraps whole segments instead of breaking words.
+const styles = stylex.create({
+	root: { flexDirection: 'row', flexWrap: 'wrap', gap: space[2], minWidth: 0 },
+	segment: {
+		flexBasis: 'auto',
+		flexGrow: 1,
+		flexShrink: 0,
+		paddingLeft: space[3],
+		paddingRight: space[3],
+	},
+})

package/node_modules/@flickfyi/core/src/molecules/stepper/stepper.tsx

@@ -0,0 +1,54 @@
+import { Flex, Icon } from '@flickfyi/core'
+import * as stylex from '@stylexjs/stylex'
+import type { PropsWithChildren } from 'react'
+
+import { Button } from '~/atoms/button/button'
+import { space } from '~/themes/scale.stylex'
+import { button } from '~/themes/shared'
+
+/** A value between square − and + controls; the value is any text or input. */
+export function Stepper({
+	children,
+	decrementDisabled = false,
+	decrementLabel,
+	incrementDisabled = false,
+	incrementLabel,
+	onDecrement,
+	onIncrement,
+}: PropsWithChildren<{
+	decrementDisabled?: boolean
+	decrementLabel: string
+	incrementDisabled?: boolean
+	incrementLabel: string
+	onDecrement: () => void
+	onIncrement: () => void
+}>) {
+	return (
+		<Flex {...stylex.props(styles.root)}>
+			<Button
+				accessibilityLabel={decrementLabel}
+				disabled={decrementDisabled}
+				onClick={onDecrement}
+				style={[button.secondary, styles.control]}
+			>
+				<Icon name="minus" />
+			</Button>
+			<Flex {...stylex.props(styles.value)}>{children}</Flex>
+			<Button
+				accessibilityLabel={incrementLabel}
+				disabled={incrementDisabled}
+				onClick={onIncrement}
+				style={[button.secondary, styles.control]}
+			>
+				<Icon name="plus" />
+			</Button>
+		</Flex>
+	)
+}
+
+// Square size-9 controls (the Button minimum on both axes) around a growing value.
+const styles = stylex.create({
+	control: { flexShrink: 0, paddingLeft: 0, paddingRight: 0 },
+	root: { alignItems: 'center', columnGap: space[2], flexDirection: 'row', minWidth: 0 },
+	value: { flexBasis: 0, flexGrow: 1, minWidth: 0 },
+})

package/node_modules/@flickfyi/core/src/quantum/use-store.ts

@@ -2,7 +2,9 @@ import type { AnyLens, InferLens } from '@flickfyi/lens'
 import { useCallback, useMemo, useSyncExternalStore } from 'react'
 
 type QuantumStore = {
+	canWrite?: boolean
 	set: (value: unknown) => void
+	setAsync?: (value: unknown) => Promise<QuantumStorePayload>
 	subscribe: (
 		callback: (raw: { rawValue: unknown; version: number }) => void
 	) => () => void
@@ -35,7 +37,8 @@ type UseStoreOptions<TLens extends AnyLens> = {
 export function createQuantumStoreAdapter<T>(
 	openStore: () => Promise<QuantumStore>,
 	initialState: T,
-	parseSnapshot: (raw: QuantumStorePayload) => Promise<T>
+	parseSnapshot: (raw: QuantumStorePayload) => Promise<T>,
+	onLoadError?: () => void
 ) {
 	let payloadGeneration = 0
 	let snapshot: T = initialState
@@ -45,6 +48,27 @@ export function createQuantumStoreAdapter<T>(
 	let storeUnsubscribe: (() => void) | undefined = undefined
 	const listeners = new Set<() => void>()
 
+	const acceptSnapshot = async (raw: QuantumStorePayload) => {
+		const generation = storeGeneration
+		const payload = ++payloadGeneration
+		let next: T
+		try {
+			next = await parseSnapshot(raw)
+		} catch (error) {
+			if (generation === storeGeneration && payload === payloadGeneration) {
+				onLoadError?.()
+			}
+			throw error
+		}
+		if (generation !== storeGeneration || payload !== payloadGeneration) {
+			return
+		}
+		snapshot = next
+		for (const listener of listeners) {
+			listener()
+		}
+	}
+
 	const ensureStore = () => {
 		if (quantumStore || storePromise) {
 			return
@@ -62,21 +86,7 @@ export function createQuantumStoreAdapter<T>(
 						return
 					}
 
-					payloadGeneration += 1
-					const payload = payloadGeneration
-					void parseSnapshot(raw)
-						.then(next => {
-							if (generation !== storeGeneration || payload !== payloadGeneration) {
-								return undefined
-							}
-
-							snapshot = next
-							for (const listener of listeners) {
-								listener()
-							}
-							return undefined
-						})
-						.catch(() => undefined)
+					void acceptSnapshot(raw).catch(() => undefined)
 				})
 				quantumStore = store
 				storeUnsubscribe = unsubscribe
@@ -90,6 +100,7 @@ export function createQuantumStoreAdapter<T>(
 				quantumStore = undefined
 				storePromise = undefined
 				storeUnsubscribe = undefined
+				onLoadError?.()
 				return undefined
 			})
 	}
@@ -104,8 +115,22 @@ export function createQuantumStoreAdapter<T>(
 	}
 
 	return {
+		acceptSnapshot,
 		getSnapshot: () => snapshot,
 		getStore: () => quantumStore,
+		/** Notify listeners after a local optimistic change or write-state update. */
+		replaceSnapshot(next: T) {
+			snapshot = next
+			for (const listener of listeners) {
+				listener()
+			}
+		},
+		retry() {
+			resetStore()
+			if (listeners.size > 0) {
+				ensureStore()
+			}
+		},
 		subscribe(onStoreChange: () => void) {
 			listeners.add(onStoreChange)
 			ensureStore()

package/node_modules/@flickfyi/core/tests/fly.test.ts

@@ -11,7 +11,7 @@ import {
 	type SharedRuntimeStore,
 } from 'fly-tsgo'
 import { createRequire } from 'module'
-import { readFileSync } from 'fs'
+import { globSync, readFileSync } from 'fs'
 import themes from '@flickfyi/core/themes'
 
 const require = createRequire(import.meta.url)
@@ -137,10 +137,10 @@ describe.skipIf(shouldSkipRemoteTests)('Fly TSGo Server Tests', () => {
 		const first = await compileWithSharedRuntime(client, hello, { store })
 		if (!first.success) throw new Error(JSON.stringify(first.errors))
 		expect(Buffer.byteLength(first.code)).toBeLessThan(10_000)
-		expect(builds).toBe(3)
+		expect(builds).toBe(4)
 		const warm = await compileWithSharedRuntime(client, hello, { store })
 		expect(warm).toEqual(first)
-		expect(builds).toBe(3)
+		expect(builds).toBe(4)
 		const themeNames = Object.keys(themes)
 		const selectedThemes = await compileWithSharedRuntime(client, buildFileMap(`
 import { Text, useTheme } from '@flickfyi/core'
@@ -155,7 +155,7 @@ export default function App() {
 		for (const name of themeNames) {
 			expect(selectedThemes.code).toContain(`@flickfyi/core/themes/${name}`)
 		}
-		expect(builds).toBe(3)
+		expect(builds).toBe(4)
 		const lens = await compileWithSharedRuntime(client, buildFileMap(`
 			import { makeLens } from '@flickfyi/lens';
 			import { z } from 'zod/v4';
@@ -163,12 +163,12 @@ export default function App() {
 		`), { store })
 		if (!lens.success) throw new Error(JSON.stringify(lens.errors))
 		expect(lens.code).not.toContain('// @flick/runtime ')
-		expect(RuntimeManifestSchema.parse(lens.runtime).libraries).toHaveLength(3)
-		expect(builds).toBe(3)
+		expect(RuntimeManifestSchema.parse(lens.runtime).libraries).toHaveLength(4)
+		expect(builds).toBe(4)
 		expect(Buffer.byteLength(lens.code)).toBeLessThan(10_000)
 		const invalid = await compileWithSharedRuntime(client, buildFileMap('export const value: number = "bad"'), { store })
 		expect(invalid.success).toBe(false)
-		expect(builds).toBe(3)
+		expect(builds).toBe(4)
 	})
 
 	it('compiles public Core atoms and molecules with inherited theme styles', async () => {
@@ -662,3 +662,30 @@ describe.skipIf(shouldSkipRemoteTests)('Sample App Compilation Tests', () => {
 		},
 	)
 })
+
+describe.skipIf(shouldSkipRemoteTests)('Canonical Persistent Feature Compilation Tests', () => {
+	const client = createClient()
+	const cached = new Map<string, RuntimeLibrary>()
+	const store: SharedRuntimeStore = {
+		async ensure(id, build) {
+			const existing = cached.get(id)
+			if (existing) return existing
+			const artifact = await build()
+			cached.set(id, artifact.library)
+			return artifact.library
+		},
+	}
+	const packageRoot = path.resolve(import.meta.dirname, '..')
+	const examples = globSync('examples/kowalski/*/*.tsx', {
+		cwd: packageRoot,
+		exclude: ['**/*.stories.tsx'],
+	}).sort()
+
+	it.each(examples)('compiles %s against the pinned shared runtime', async entry => {
+		const files = buildFileMap(readFileSync(path.resolve(packageRoot, entry), 'utf8'))
+		const result = await compileWithSharedRuntime(client, files, { store })
+		if (!result.success) throw new Error(`${entry}: ${JSON.stringify(result.errors)}`)
+		expect(result.code).toContain('@flickfyi/core/kowalski')
+		expect(RuntimeManifestSchema.parse(result.runtime).libraries).toHaveLength(4)
+	}, 60_000)
+})

package/node_modules/@flickfyi/core/tests/kowalski-calculations.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+	billShares,
+	convertUnit,
+	elapsedSeconds,
+	localDate,
+	nextReminder,
+	pickResult,
+} from '~/kowalski/calculations'
+
+describe('Kowalski calculations', () => {
+	it('restores elapsed time from an anchor, handles clock reversal, and pauses without drift', () => {
+		expect(elapsedSeconds({ elapsedSeconds: 12, startedAt: 1000 }, 11_000)).toBe(22)
+		expect(elapsedSeconds({ elapsedSeconds: 12, startedAt: 1000 }, 0)).toBe(12)
+		expect(elapsedSeconds({ elapsedSeconds: 12, startedAt: null }, 11_000)).toBe(12)
+	})
+	it('keeps per-person currency shares exact without dropping a minor unit', () => {
+		expect(billShares(10, 3, 0, 'USD')).toEqual({
+			perPerson: 3.33,
+			remainder: 0.01,
+			total: 10,
+		})
+		expect(billShares(100, 3, 0, 'JPY')).toEqual({
+			perPerson: 33,
+			remainder: 1,
+			total: 100,
+		})
+		expect(billShares(10, 2, 20, 'USD').perPerson).toBe(6)
+		expect(billShares(17.15, 1, 10, 'USD').total).toBe(18.87)
+		expect(billShares(2.75, 1, 18, 'USD').total).toBe(3.25)
+	})
+	it('converts length, mass, and temperature with their offsets', () => {
+		expect(convertUnit(1, 'mi', 'km')).toBeCloseTo(1.609344)
+		expect(convertUnit(32, 'f', 'c')).toBe(0)
+		expect(convertUnit(273.15, 'k', 'c')).toBe(0)
+		expect(convertUnit(0.1, 'm', 'km')).toBe(0.0001)
+		expect(convertUnit(0, 'c', 'k')).toBeCloseTo(273.15)
+		expect(convertUnit(0.0000001, 'k', 'k')).toBe(0.0000001)
+		expect(() => convertUnit(1, 'kg', 'km')).toThrow()
+	})
+	it('uses the selected calendar date across UTC midnight', () => {
+		expect(localDate(Date.parse('2026-10-15T01:00:00Z'), 'America/Los_Angeles')).toBe(
+			'2026-10-14'
+		)
+		expect(localDate(Date.parse('2026-10-15T01:00:00Z'), 'Asia/Tokyo')).toBe('2026-10-15')
+	})
+	it('advances a stale repeating reminder to the next future occurrence', () => {
+		expect(
+			nextReminder('2026-10-10T09:00:00Z', 'daily', Date.parse('2026-10-15T10:00:00Z'))
+		).toBe('2026-10-16T09:00:00.000Z')
+		expect(nextReminder(null, 'daily', 0)).toBeNull()
+	})
+	it('samples both ends of an inclusive range and rejects invalid randomness', () => {
+		const domain = { maximum: 2, minimum: -2, mode: 'range' as const }
+		expect(pickResult(domain, 0)).toBe(-2)
+		expect(pickResult(domain, 0.99999)).toBe(2)
+		expect(() => pickResult(domain, 1)).toThrow()
+	})
+})