@flickfyi/flkr 0.0.182 → 0.0.185

package/node_modules/@flickfyi/core/examples/parrott/kale-smoothie/kale-smoothie.tsx

@@ -2,8 +2,6 @@ import { useTheme } from '@flickfyi/core'
 import { Card, List, QuantityGroup, Stat } from '@flickfyi/core/molecules'
 import { useState } from 'react'
 
-import type { ExampleMetadata } from '@flickfyi/core/examples/metadata'
-
 import { theme } from './theme'
 
 // Nutrition data per unit
@@ -101,9 +99,3 @@ export default function KaleSmoothieMacroCalculator() {
 		</Card>
 	)
 }
-
-export const exampleMetadata = {
-	description:
-		'Weighted totals from several independently adjustable quantities and per-unit factors, such as calories and nutrients across ingredients. Shows per-item quantity controls and recomputes aggregate measures.',
-	name: 'Quantity totals',
-} satisfies ExampleMetadata

package/node_modules/@flickfyi/core/examples/parrott/list/list.stories.tsx

@@ -1,4 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Meta } from '@storybook/react-vite'
+
+import type { ExampleStory } from '@flickfyi/core/examples/metadata'
 
 import { List } from './list'
 import exampleSource from './list.tsx?raw'
@@ -10,6 +12,11 @@ const meta = {
 } satisfies Meta<typeof List>
 
 export default meta
-export const Example: StoryObj<typeof meta> = {
-	args: { enabledForAgents: true },
+export const Example: ExampleStory<typeof meta> = {
+	args: {
+		description:
+			'Sortable rows with primary and secondary labels, relative timestamps, a per-row action, useful for schedules and recurring follow-ups.',
+		enabled: true,
+		name: 'Actionable list',
+	},
 }

package/node_modules/@flickfyi/core/examples/parrott/list/list.tsx

@@ -3,8 +3,6 @@ import { Card, List as ItemList } from '@flickfyi/core/molecules'
 import * as stylex from '@flickfyi/core/stylex'
 import { useEffect, useState } from 'react'
 
-import type { ExampleMetadata } from '@flickfyi/core/examples/metadata'
-
 import { theme } from './theme'
 
 type Contact = { id: string; lastCalled: number | undefined; name: string }
@@ -88,12 +86,6 @@ export const evalMetadata = {
 	prompt: 'Make a weekly call sheet for family',
 }
 
-export const exampleMetadata = {
-	description:
-		'Sortable rows with primary and secondary labels, relative timestamps, a per-row action, useful for schedules and recurring follow-ups.',
-	name: 'Actionable list',
-} satisfies ExampleMetadata
-
 function daysSince(ts: number | undefined, now: number): number {
 	if (ts === undefined) {
 		return Infinity

package/node_modules/@flickfyi/core/examples/parrott/log/log.stories.tsx

@@ -1,4 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Meta } from '@storybook/react-vite'
+
+import type { ExampleStory } from '@flickfyi/core/examples/metadata'
 
 import { Log } from './log'
 import exampleSource from './log.tsx?raw'
@@ -10,6 +12,11 @@ const meta = {
 } satisfies Meta<typeof Log>
 
 export default meta
-export const Example: StoryObj<typeof meta> = {
-	args: { enabledForAgents: true },
+export const Example: ExampleStory<typeof meta> = {
+	args: {
+		description:
+			'Appending timestamped outcomes to an event history, newest first, with totals and a success percentage derived from recorded events. For recording occurrences rather than updating the current value of an existing item.',
+		enabled: true,
+		name: 'Event log',
+	},
 }

package/node_modules/@flickfyi/core/examples/parrott/log/log.tsx

@@ -4,8 +4,6 @@ import { Card, List, Progress } from '@flickfyi/core/molecules'
 import * as stylex from '@flickfyi/core/stylex'
 import { useState } from 'react'
 
-import type { ExampleMetadata } from '@flickfyi/core/examples/metadata'
-
 import { theme } from './theme'
 
 type Shot = { id: string; made: boolean; time: string }
@@ -79,12 +77,6 @@ export const evalMetadata = {
 	prompt: 'Make a free throw tracker',
 }
 
-export const exampleMetadata = {
-	description:
-		'Appending timestamped outcomes to an event history, newest first, with totals and a success percentage derived from recorded events. For recording occurrences rather than updating the current value of an existing item.',
-	name: 'Event log',
-} satisfies ExampleMetadata
-
 const formatTime = () => {
 	const d = new Date()
 	const h = d.getHours()

package/node_modules/@flickfyi/core/examples/parrott/timed-task/timed-task.stories.tsx

@@ -1,4 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Meta } from '@storybook/react-vite'
+
+import type { ExampleStory } from '@flickfyi/core/examples/metadata'
 
 import TimedTask from './timed-task'
 import exampleSource from './timed-task.tsx?raw'
@@ -10,6 +12,11 @@ const meta = {
 } satisfies Meta<typeof TimedTask>
 
 export default meta
-export const Example: StoryObj<typeof meta> = {
-	args: { enabledForAgents: true },
+export const Example: ExampleStory<typeof meta> = {
+	args: {
+		description:
+			'A preparation checklist with preparation-only progress, followed by a separately started countdown with pause/resume, then finishing actions and completion. For multi-stage timed workflows.',
+		enabled: true,
+		name: 'Prepare, time, finish',
+	},
 }

package/node_modules/@flickfyi/core/examples/parrott/timed-task/timed-task.tsx

@@ -4,8 +4,6 @@ import { Card, Choice, List, Progress, Stat } from '@flickfyi/core/molecules'
 import * as stylex from '@flickfyi/core/stylex'
 import { useEffect, useState } from 'react'
 
-import type { ExampleMetadata } from '@flickfyi/core/examples/metadata'
-
 import { theme } from './theme'
 
 const duration = 2 * 60 * 1000
@@ -150,9 +148,3 @@ export default function TimedTask() {
 		</Card>
 	)
 }
-
-export const exampleMetadata = {
-	description:
-		'A preparation checklist with preparation-only progress, followed by a separately started countdown with pause/resume, then finishing actions and completion. For multi-stage timed workflows.',
-	name: 'Prepare, time, finish',
-} satisfies ExampleMetadata

package/node_modules/@flickfyi/core/examples/parrott/timer/timer.stories.tsx

@@ -1,4 +1,6 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Meta } from '@storybook/react-vite'
+
+import type { ExampleStory } from '@flickfyi/core/examples/metadata'
 
 import Timer from './timer'
 import exampleSource from './timer.tsx?raw'
@@ -10,6 +12,11 @@ const meta = {
 } satisfies Meta<typeof Timer>
 
 export default meta
-export const Example: StoryObj<typeof meta> = {
-	args: { enabledForAgents: true },
+export const Example: ExampleStory<typeof meta> = {
+	args: {
+		description:
+			'A user-started countdown with pause, resume, reset, and stable completion, useful for cooking, brewing, and timed activities.',
+		enabled: true,
+		name: 'Countdown timer',
+	},
 }

package/node_modules/@flickfyi/core/examples/parrott/timer/timer.tsx

@@ -3,8 +3,6 @@ import { Button } from '@flickfyi/core/atoms'
 import { Card, Stat } from '@flickfyi/core/molecules'
 import { useEffect, useState } from 'react'
 
-import type { ExampleMetadata } from '@flickfyi/core/examples/metadata'
-
 import { theme } from './theme'
 
 const duration = 90 * 1000
@@ -74,9 +72,3 @@ export default function Timer() {
 		</Card>
 	)
 }
-
-export const exampleMetadata = {
-	description:
-		'A user-started countdown with pause, resume, reset, and stable completion, useful for cooking, brewing, and timed activities.',
-	name: 'Countdown timer',
-} satisfies ExampleMetadata

package/node_modules/@flickfyi/core/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flickfyi/core",
-	"version": "0.0.69",
+	"version": "0.0.72",
 	"description": "Core type definitions and runtime environment for JavaScriptCore",
 	"license": "MIT",
 	"files": [
@@ -180,6 +180,16 @@
 				"default": "./dist/kowalski/catalog.cjs"
 			}
 		},
+		"./kowalski/schemas": {
+			"import": {
+				"types": "./dist-types/kowalski/schemas.d.ts",
+				"default": "./dist/kowalski/schemas.js"
+			},
+			"require": {
+				"types": "./dist-types/kowalski/schemas.d.cts",
+				"default": "./dist/kowalski/schemas.cjs"
+			}
+		},
 		"./examples/kowalski/theme": "./examples/kowalski/theme.ts",
 		"./examples/kowalski/*": "./examples/kowalski/*/*.tsx",
 		"./examples/kowalski/*.tsx": "./examples/kowalski/*.tsx"
@@ -197,7 +207,7 @@
 		"deploy": "npm run verify:tsgo && npm run deploy:tsgo-deps && op run --env-file=\".env.op\" -- bun x --no-install fly-tsgo publish",
 		"deploy:tsgo-deps": "tsx scripts/deploy-tsgo-workspace-deps.ts",
 		"prepack": "npm run verify:tsgo",
-		"typecheck": "tsrs --noEmit -p ./tsconfig.json && tsrs --noEmit -p ./tsconfig.examples.json",
+		"typecheck": "bun ./build-entries.ts && tsrs --noEmit -p ./tsconfig.json && tsrs --noEmit -p ./tsconfig.examples.json",
 		"prebuild:types": "npm run verify:generated-types",
 		"generate:types": "bun run --filter @flickfyi/photon generate-types",
 		"generate:fonts": "tsx ./scripts/generate-google-fonts.ts",
@@ -281,6 +291,9 @@
 		"vite": "8.3.5",
 		"vite-plugin-dts": "5.1.2",
 		"vitest": "5.0.5",
-		"zx": "8.8.5"
+		"zx": "8.8.5",
+		"@flickfyi/schemas": "0.0.0",
+		"eslint": "10.14.0",
+		"@typescript-eslint/parser": "8.72.1"
 	}
 }

package/node_modules/@flickfyi/core/src/{kowalski/use-configured-feature.ts → hooks/use-configured-feature/index.ts}

@@ -1,7 +1,7 @@
 import { useEffect, useMemo } from 'react'
 import type { z } from 'zod/v4'
 
-import { useFeatureStore } from './use-feature-store'
+import { useFeatureStore } from '~/hooks/use-feature-store'
 
 /** Authored seeds change only at a newer manifest revision; live values otherwise win. */
 export function useConfiguredFeature<

package/node_modules/@flickfyi/core/src/{kowalski/use-feature-store.ts → hooks/use-feature-store/index.ts}

@@ -4,18 +4,23 @@ 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'
-}) {
+/**
+ * Subscribes to a Quantum store and exposes optimistic writes after hydration.
+ *
+ * @typeParam T - The state validated by the store schema.
+ * @param options - The store identity, schema, initial state, and sharing scope.
+ * @returns The visible state and save status. `set` accepts a partial update or an
+ * updater function and returns whether the write was queued; its optional callback
+ * runs after persistence succeeds. `ready` means the store is hydrated and writable.
+ * `retry` is available after a load failure. Failed writes roll back and set `error`.
+ *
+ * @remarks
+ * Public stores share state between users of the same flick. Pass `scope: 'private'`
+ * for separate state per user. Changing the name or scope opens a different store;
+ * it does not migrate existing data.
+ */
+export function useFeatureStore<T extends object>(options: UseFeatureStoreOptions<T>) {
+	const { initialState, name, schema, scope = 'public' } = options
 	const lens = useMemo(() => makeLens({ schema }), [schema])
 	const writes = useMemo<{ pending: Set<Partial<T>>; error?: string }>(
 		() => ({ pending: new Set() }),
@@ -105,6 +110,26 @@ export function useFeatureStore<T extends object>({
 	}
 }
 
+/**
+ * Options for {@link useFeatureStore}.
+ *
+ * @typeParam T - The state validated by `schema`.
+ */
+export type UseFeatureStoreOptions<T extends object> = {
+	/** Seeds a new store and supplies the value before hydration; never replaces saved state. */
+	initialState: T
+	/** Stable store name within the flick. Reuse it to reopen the same store and scope. */
+	name: string
+	/** Validates snapshots and updates and determines the store version. Keep its reference stable. */
+	schema: z.ZodType<T>
+	/**
+	 * Whether state is shared between users of the flick or kept separately per user.
+	 *
+	 * @defaultValue `'public'`
+	 */
+	scope?: 'private' | 'public'
+}
+
 type FeatureSnapshot<T> = {
 	loadFailed?: boolean
 	ready: boolean

package/node_modules/@flickfyi/core/src/kowalski/README.md

@@ -7,3 +7,16 @@
 5. Minimize the setup interface once the activity has begun.
 6. Items waiting on something else stay grey, deferred until it completes.
 7. Ideally it should fit on the screen, but don't be excessively dogmatic.
+
+## Props
+
+Props are typed by TypeScript. Components destructure them with defaults and never parse
+or validate their own props at runtime (no `Props.parse(input)` in a component).
+
+Each component's `data` schema lives in that component's file; helpers shared across features
+live in `feature-schema.ts`. Content schemas are what the content model reads, so they describe
+each field and nothing else: no `.min()`, `.max()`, `.int()`, `.regex()`, `.refine()`,
+`.default()`, or `z.iso` formats. Say "short" or "Omit for 300" in `.describe()` instead, and
+apply the fallback in the component. Components render whatever content they receive, including
+empty strings, empty arrays, and unparseable dates, time zones, or currency codes, without
+throwing. `tests/kowalski-contracts.test.ts` checks the content schemas for these keywords.

package/node_modules/@flickfyi/core/src/kowalski/calculations.ts

@@ -1,7 +1,21 @@
 import { Decimal } from 'decimal.js'
 
-import { type PickerDomain, unitDefinitions } from './catalog'
-import { format } from './format'
+import type { PickerDomain } from '~/kowalski/components/random-picker'
+
+import { format, resolveCurrency } from './format'
+
+export const unitDefinitions = {
+	c: { dimension: 'temperature', factor: 1, offset: 0 },
+	f: { dimension: 'temperature', factor: 5 / 9, offset: -32 },
+	ft: { dimension: 'length', factor: 0.3048, offset: 0 },
+	g: { dimension: 'mass', factor: 0.001, offset: 0 },
+	k: { dimension: 'temperature', factor: 1, offset: -273.15 },
+	kg: { dimension: 'mass', factor: 1, offset: 0 },
+	km: { dimension: 'length', factor: 1000, offset: 0 },
+	lb: { dimension: 'mass', factor: 0.45359237, offset: 0 },
+	m: { dimension: 'length', factor: 1, offset: 0 },
+	mi: { dimension: 'length', factor: 1609.344, offset: 0 },
+}
 
 const Money = Decimal.clone({ precision: 40, rounding: Decimal.ROUND_HALF_UP })
 
@@ -19,21 +33,26 @@ export function billShares(
 	total: number,
 	people: number,
 	tipPercent: number,
-	currency: string
+	currency: string | undefined
 ) {
 	const digits =
 		format.formatters
-			.getNumberFormat(format.locale, { currency, style: 'currency' })
+			.getNumberFormat(format.locale, {
+				currency: resolveCurrency(currency),
+				style: 'currency',
+			})
 			.resolvedOptions().maximumFractionDigits ?? 2
 	const scale = 10 ** digits
 	const minor = new Money(total)
 		.times(new Money(tipPercent).div(100).plus(1))
 		.times(scale)
 		.toDecimalPlaces(0)
-	const share = minor.dividedToIntegerBy(people)
+	// Authored and stored counts are unvalidated; split between at least one whole person.
+	const count = Number.isFinite(people) ? Math.max(1, Math.round(people)) : 1
+	const share = minor.dividedToIntegerBy(count)
 	return {
 		perPerson: share.div(scale).toNumber(),
-		remainder: minor.minus(share.times(people)).div(scale).toNumber(),
+		remainder: minor.minus(share.times(count)).div(scale).toNumber(),
 		total: minor.div(scale).toNumber(),
 	}
 }
@@ -77,11 +96,20 @@ export function nextReminder(
 	}
 	const interval = (recurrence === 'daily' ? 1 : 7) * 86_400_000
 	const due = Date.parse(dueAt)
+	if (!Number.isFinite(due)) {
+		return null
+	}
 	return new Date(
 		due + Math.max(1, Math.floor((now - due) / interval) + 1) * interval
 	).toISOString()
 }
 
+/** Stored and authored instants are unvalidated text; anything unparseable reads as unset. */
+export function parseInstant(value: string | null | undefined) {
+	const instant = value ? Date.parse(value) : Number.NaN
+	return Number.isFinite(instant) ? instant : null
+}
+
 export function pickResult(domain: PickerDomain, sample: number) {
 	if (!(sample >= 0 && sample < 1)) {
 		throw new Error('Random sample must be in [0, 1)')
@@ -97,9 +125,9 @@ export function pickResult(domain: PickerDomain, sample: number) {
 }
 
 /** Currency padding and grouping stay identical in the saved card and its editor. */
-export function formatCurrency(value: number, currency: string) {
+export function formatCurrency(value: number, currency: string | undefined) {
 	return format.formatNumber(value, {
-		currency,
+		currency: resolveCurrency(currency),
 		format: 'decimal',
 		style: 'currency',
 	})

package/node_modules/@flickfyi/core/src/kowalski/calculator.ts

@@ -1,10 +1,15 @@
 import { Decimal } from 'decimal.js'
+import type { z } from 'zod/v4'
+
+import type {
+	CalculatorData,
+	calculatorStoreSchema,
+} from '~/kowalski/components/calculator'
 
-import type { KowalskiProps, KowalskiState } from './catalog'
 import { format } from './format'
 
-type CalculatorState = KowalskiState<'calculator'>['calculation']
-type CalculatorOperator = KowalskiProps<'calculator'>['operator']
+type CalculatorState = z.output<typeof calculatorStoreSchema>['calculation']
+type CalculatorOperator = NonNullable<z.output<typeof CalculatorData>['operator']>
 export type CalculatorKey =
 	| '0'
 	| '1'
@@ -50,10 +55,13 @@ export const calculatorKeys = [
 ] satisfies CalculatorKey[]
 
 export function initialCalculator({
-	left,
-	operator,
-	right,
-}: Pick<KowalskiProps<'calculator'>, 'left' | 'operator' | 'right'>): CalculatorState {
+	left = 0,
+	operator = '+',
+	right = 0,
+}: Pick<
+	z.output<typeof CalculatorData>,
+	'left' | 'operator' | 'right'
+>): CalculatorState {
 	const result = calculate(left, operator, right)
 	return {
 		entry: result === null ? 'Error' : new CalculatorNumber(result).toString(),