\n Send Message\n

\n\n

\n \n Message Text:\n \n setText(e.target.value)}\n placeholder=\"HELLO WORLD\"\n maxLength={100}\n required\n style={{\n width: \"100%\",\n padding: \"0.5rem\",\n border: \"1px solid #d1d5db\",\n borderRadius: \"4px\",\n fontSize: \"1rem\",\n }}\n />\n \n Text longer than display width will auto-scroll\n \n

\n\n

\n \n setScroll(e.target.checked)}\n style={{ width: \"auto\" }}\n />\n \n Force scrolling (even for short text)\n \n \n

\n\n

\n \n Priority: {priority}\n \n setPriority(Number(e.target.value))}\n min=\"0\"\n max=\"100\"\n style={{ width: \"100%\" }}\n />\n \n Higher priority messages override lower priority (Clock is 10)\n \n

\n\n

\n \n Duration: {duration}s\n \n setDuration(Number(e.target.value))}\n min=\"10\"\n max=\"300\"\n step=\"10\"\n style={{ width: \"100%\" }}\n />\n

\n\n

\n \n Send Message\n \n\n \n {isPolling ? \"Pause\" : \"Resume\"}\n \n\n \n Clear All\n \n

\n\n \n

\n Priority Guide:\n

Clock: 10 (default, always visible)
Text messages: 20-40 (temporary override)
Alerts: 50-100 (high priority)

\n \n \n );\n}\n",[],[297,303,310],{"_102":318,"_95":319,"_152":320,"_154":304,"_155":137,"_156":321,"_158":159,"_104":322,"_99":290,"_161":198,"_163":323,"_164":22,"_165":-5,"_166":324,"_98":325},"96455546-bcd4-11f0-87ec-42dde27851f2","Display.tsx","cc7c837c-bcd0-11f0-bf01-42dde27851f2",61,["D",1762628168854],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\n\ninterface DisplayProps {\n bits: number[];\n isPolling: boolean;\n}\n\nexport function Display({ bits, isPolling }: DisplayProps) {\n const DISPLAY_WIDTH = 28;\n const DISPLAY_HEIGHT = 14;\n\n return (\n \n \n \n {isPolling ? \"Live (polling every 2s)\" : \"Paused\"}\n \n\n \n {bits.map((bit, idx) => (\n \n ))}\n \n\n \n \n );\n}\n",[],[297,303,319],{"_102":327,"_95":328,"_152":329,"_154":304,"_155":137,"_156":330,"_158":159,"_104":331,"_99":32,"_161":198,"_163":332,"_164":22,"_165":-5,"_166":333,"_98":334},"9dc71752-bcd2-11f0-b7e4-42dde27851f2","LoginForm.tsx","9dc71824-bcd2-11f0-b7e4-42dde27851f2",54,["D",1762627322461],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { useState } from \"https://esm.sh/react@18.2.0\";\nimport { useLogin } from \"../hooks/useAuth.ts\";\n\nexport interface LoginFormProps {\n onLogin: () => void;\n}\n\nexport function LoginForm({ onLogin }: LoginFormProps) {\n const [password, setPassword] = useState(\"\");\n const loginMutation = useLogin(onLogin);\n\n const handleSubmit = (e: React.FormEvent) => {\n e.preventDefault();\n loginMutation.mutate(password);\n };\n\n return (\n \n

\n \n Sign in to FlipDot Control\n \n \n

\n \n Password\n \n setPassword(e.target.value)}\n />\n

\n {loginMutation.error && (\n \n {loginMutation.error.message}\n

\n )}\n

\n \n {loginMutation.isPending ? \"Signing in...\" : \"Sign in\"}\n \n

\n \n \n \n );\n}\n",[],[297,303,328],{"_102":336,"_95":337,"_152":338,"_154":304,"_155":137,"_156":339,"_158":159,"_104":340,"_99":32,"_161":198,"_163":341,"_164":22,"_165":-5,"_166":342,"_98":343},"ccea1a90-bcd0-11f0-a582-42dde27851f2","StatusMessage.tsx","ccea1b44-bcd0-11f0-a582-42dde27851f2",28,["D",1762626541915],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { useEffect } from \"https://esm.sh/react@18.2.0\";\n\ninterface StatusMessageProps {\n type: \"success\" | \"error\" | \"info\";\n text: string;\n onDismiss: () => void;\n}\n\nexport function StatusMessage({ type, text, onDismiss }: StatusMessageProps) {\n useEffect(() => {\n const timer = setTimeout(onDismiss, 5000);\n return () => clearTimeout(timer);\n }, [onDismiss]);\n\n const colors = {\n success: { bg: \"#d1fae5\", border: \"#10b981\", text: \"#065f46\" },\n error: { bg: \"#fee2e2\", border: \"#ef4444\", text: \"#991b1b\" },\n info: { bg: \"#dbeafe\", border: \"#3b82f6\", text: \"#1e40af\" },\n };\n\n const color = colors[type];\n\n return (\n \n {text}\n \n ×\n \n \n );\n}\n",[],[297,303,337],[297,303],{"_102":346,"_95":347,"_152":348,"_154":298,"_155":137,"_156":349,"_158":159,"_104":350,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_166":351,"_98":361},"8e4d6934-bcd2-11f0-b0df-42dde27851f2","hooks","8e4d6a06-bcd2-11f0-b0df-42dde27851f2",50,["D",1762627296500],[352],{"_102":353,"_95":354,"_152":355,"_154":348,"_155":137,"_156":356,"_158":159,"_104":357,"_99":32,"_161":198,"_163":358,"_164":22,"_165":-5,"_166":359,"_98":360},"8e5b9b08-bcd2-11f0-a759-42dde27851f2","useAuth.ts","8e5b9bd0-bcd2-11f0-a759-42dde27851f2",51,["D",1762627296594],"import {\n useMutation,\n useQuery,\n useQueryClient,\n} from \"https://esm.sh/@tanstack/react-query@5.56.2?deps=react@18.2.0\";\nimport { authApi } from \"../services/api.ts\";\n\nexport const useAuthCheck = () => {\n return useQuery({\n queryKey: [\"auth\"],\n queryFn: authApi.checkAuth,\n retry: false,\n staleTime: 5 * 60 * 1000, // 5 minutes\n });\n};\n\nexport const useLogin = (onSuccess?: () => void) => {\n const queryClient = useQueryClient();\n\n return useMutation({\n mutationFn: authApi.login,\n onSuccess: () => {\n queryClient.setQueryData([\"auth\"], true);\n onSuccess?.();\n },\n });\n};\n\nexport const useLogout = (onSuccess?: () => void) => {\n const queryClient = useQueryClient();\n\n return useMutation({\n mutationFn: authApi.logout,\n onSuccess: () => {\n queryClient.setQueryData([\"auth\"], false);\n queryClient.clear(); // Clear all cached data on logout\n onSuccess?.();\n },\n });\n};\n",[],[297,347,354],[297,347],{"_102":363,"_95":364,"_152":365,"_154":298,"_155":137,"_156":366,"_158":159,"_104":367,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_166":368,"_98":378},"9300e078-bcd2-11f0-86ca-42dde27851f2","providers","9300e168-bcd2-11f0-86ca-42dde27851f2",52,["D",1762627304389],[369],{"_102":370,"_95":371,"_152":372,"_154":365,"_155":137,"_156":373,"_158":159,"_104":374,"_99":32,"_161":198,"_163":375,"_164":22,"_165":-5,"_166":376,"_98":377},"930d8d8c-bcd2-11f0-86ca-42dde27851f2","QueryProvider.tsx","930d8e5e-bcd2-11f0-86ca-42dde27851f2",53,["D",1762627304473],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\nimport {\n QueryClient,\n QueryClientProvider,\n} from \"https://esm.sh/@tanstack/react-query@5.56.2?deps=react@18.2.0\";\n\nconst queryClient = new QueryClient({\n defaultOptions: {\n queries: {\n refetchOnWindowFocus: false,\n retry: 1,\n },\n },\n});\n\nexport function QueryProvider({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n",[],[297,364,371],[297,364],{"_102":380,"_95":381,"_152":382,"_154":298,"_155":137,"_156":383,"_158":159,"_104":384,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_166":385,"_98":395},"8907a2be-bcd2-11f0-a963-42dde27851f2","services","8907a354-bcd2-11f0-a963-42dde27851f2",48,["D",1762627287655],[386],{"_102":387,"_95":388,"_152":389,"_154":382,"_155":137,"_156":390,"_158":159,"_104":391,"_99":32,"_161":198,"_163":392,"_164":22,"_165":-5,"_166":393,"_98":394},"8913bc34-bcd2-11f0-b6b8-42dde27851f2","api.ts","8913bce8-bcd2-11f0-b6b8-42dde27851f2",49,["D",1762627287736],"/**\n * API client for FlipDot frontend\n */\n\n// Auth API\nexport const authApi = {\n login: async (password: string) => {\n const response = await fetch(\"/api/auth/login\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ password }),\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(error.error || \"Invalid password\");\n }\n\n return response.json();\n },\n\n logout: async () => {\n const response = await fetch(\"/api/auth/logout\", {\n method: \"POST\",\n });\n\n if (!response.ok) {\n throw new Error(\"Logout failed\");\n }\n\n return response.json();\n },\n\n checkAuth: async () => {\n const response = await fetch(\"/api/auth/check\");\n\n if (!response.ok) {\n return false;\n }\n\n const data = await response.json();\n return data.authenticated;\n },\n};\n",[],[297,381,388],[297,381],{"_102":397,"_95":398,"_152":399,"_154":298,"_155":137,"_156":136,"_158":159,"_104":400,"_99":401,"_161":198,"_163":402,"_164":22,"_165":-5,"_166":403,"_98":404},"308ee948-bcd8-11f0-80d2-42dde27851f2","App.tsx","cc883af0-bcd0-11f0-bb09-42dde27851f2",["D",1762629716171],13,"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { useEffect, useState } from \"https://esm.sh/react@18.2.0\";\nimport { Display } from \"./components/Display.tsx\";\nimport { ControlPanel } from \"./components/ControlPanel.tsx\";\nimport { StatusMessage } from \"./components/StatusMessage.tsx\";\nimport { LoginForm } from \"./components/LoginForm.tsx\";\nimport { useAuthCheck } from \"./hooks/useAuth.ts\";\n\nexport function App() {\n const { data: authenticated, isLoading, refetch } = useAuthCheck();\n\n // Show loading state while checking auth\n if (isLoading) {\n return (\n \n

\n Loading...\n

\n \n );\n }\n\n // Show login form if not authenticated\n if (!authenticated) {\n return refetch()} />;\n }\n\n // User is authenticated, show the main app\n return ;\n}\n\nfunction AuthenticatedApp() {\n const [displayBits, setDisplayBits] = useState(\n new Array(28 * 14).fill(0),\n );\n const [statusMessage, setStatusMessage] = useState<\n {\n type: \"success\" | \"error\" | \"info\";\n text: string;\n } | null\n >(null);\n const [isPolling, setIsPolling] = useState(false);\n const [currentContent, setCurrentContent] = useState(null);\n\n // Helper function to decode a frame\n const decodeFrame = (frame: any): number[] => {\n const decoded = atob(frame.data_b64);\n const bytes = new Uint8Array(decoded.length);\n for (let i = 0; i < decoded.length; i++) {\n bytes[i] = decoded.charCodeAt(i);\n }\n\n // Unpack bits (little-endian)\n const bits: number[] = [];\n for (let byteIdx = 0; byteIdx < bytes.length; byteIdx++) {\n for (let bitIdx = 0; bitIdx < 8; bitIdx++) {\n if (bits.length < 28 * 14) {\n bits.push((bytes[byteIdx] >> bitIdx) & 1);\n }\n }\n }\n return bits;\n };\n\n // Animate through frames\n useEffect(() => {\n if (\n !currentContent || !currentContent.frames ||\n currentContent.frames.length === 0\n ) {\n return;\n }\n\n const frames = currentContent.frames;\n const playback = currentContent.playback || {};\n const shouldLoop = playback.loop !== false; // Default to true\n\n let currentFrameIndex = 0;\n let animationTimeout: number;\n\n const showNextFrame = () => {\n if (currentFrameIndex >= frames.length) {\n if (shouldLoop) {\n currentFrameIndex = 0; // Loop back to start\n } else {\n return; // Stop animation\n }\n }\n\n const frame = frames[currentFrameIndex];\n const bits = decodeFrame(frame);\n setDisplayBits(bits);\n\n const duration = frame.duration_ms || 100; // Default 100ms per frame\n currentFrameIndex++;\n\n animationTimeout = globalThis.setTimeout(showNextFrame, duration);\n };\n\n // Start animation\n showNextFrame();\n\n return () => {\n if (animationTimeout) clearTimeout(animationTimeout);\n };\n }, [currentContent]);\n\n // Poll the content endpoint to update display\n useEffect(() => {\n let interval: number;\n\n const pollContent = async () => {\n try {\n const response = await fetch(\"/api/flipdot/content\", {\n headers: {\n \"X-API-Key\": \"local-dev-key\",\n },\n });\n\n if (response.ok) {\n const data = await response.json();\n\n if (data.status === \"updated\" && data.content) {\n setCurrentContent(data.content);\n } else if (data.status === \"clear\") {\n setCurrentContent(null);\n setDisplayBits(new Array(28 * 14).fill(0));\n }\n }\n } catch (error) {\n console.error(\"Error polling content:\", error);\n }\n };\n\n if (isPolling) {\n pollContent(); // Initial poll\n interval = globalThis.setInterval(pollContent, 2000); // Poll every 2s\n }\n\n return () => {\n if (interval) clearInterval(interval);\n };\n }, [isPolling]);\n\n // Auto-start polling\n useEffect(() => {\n setIsPolling(true);\n }, []);\n\n const handleSendMessage = async (formData: {\n text: string;\n priority: number;\n duration: number;\n scroll: boolean;\n }) => {\n try {\n const response = await fetch(\"/api/flipdot/text\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"X-API-Key\": \"local-dev-key\",\n },\n body: JSON.stringify({\n text: formData.text.toUpperCase(),\n priority: formData.priority,\n ttl_ms: formData.duration * 1000,\n scroll: formData.scroll,\n }),\n });\n\n const result = await response.json();\n\n if (response.ok) {\n const typeMsg = result.type === \"scrolling_text\" ? \" (Scrolling)\" : \"\";\n setStatusMessage({\n type: \"success\",\n text: `Message sent! Priority: ${formData.priority}${typeMsg}`,\n });\n } else {\n setStatusMessage({\n type: \"error\",\n text: result.error || \"Failed to send message\",\n });\n }\n } catch (error) {\n setStatusMessage({\n type: \"error\",\n text: \"Network error: \" + (error as Error).message,\n });\n }\n };\n\n const handleClearAll = async () => {\n try {\n const response = await fetch(\"/api/flipdot/clear\", {\n method: \"POST\",\n headers: {\n \"X-API-Key\": \"local-dev-key\",\n },\n });\n\n if (response.ok) {\n setStatusMessage({\n type: \"success\",\n text: \"All messages cleared\",\n });\n setDisplayBits(new Array(28 * 14).fill(0));\n } else {\n const result = await response.json();\n setStatusMessage({\n type: \"error\",\n text: result.error || \"Failed to clear messages\",\n });\n }\n } catch (error) {\n setStatusMessage({\n type: \"error\",\n text: \"Network error: \" + (error as Error).message,\n });\n }\n };\n\n return (\n

\n FlipDot Display Control\n

\n 28×14 Pixel Display Simulator\n

\n\n \n \n

\n setIsPolling(!isPolling)}\n isPolling={isPolling}\n />\n {statusMessage && (\n setStatusMessage(null)}\n />\n )}\n

\n\n \n

\n Content Server v2.0 |{\" \"}\n \n View API\n \n

\n \n \n );\n}\n",[],[297,398],{"_102":406,"_95":407,"_152":408,"_154":298,"_155":137,"_156":409,"_158":159,"_104":410,"_99":32,"_161":174,"_163":411,"_164":22,"_165":-5,"_166":412,"_98":413},"cc75d77a-bcd0-11f0-a582-42dde27851f2","index.html","cc75d824-bcd0-11f0-a582-42dde27851f2",8,["D",1762626541793],"\n\n\n \n \n FlipDot Display Control\n \n\n\n

\n \n \n\n\n",[],[297,407],{"_102":415,"_95":416,"_152":417,"_154":298,"_155":137,"_156":418,"_158":159,"_104":419,"_99":290,"_161":198,"_163":420,"_164":22,"_165":-5,"_166":421,"_98":422},"b20f841a-bcd2-11f0-a74f-42dde27851f2","index.tsx","cc831250-bcd0-11f0-a677-42dde27851f2",56,["D",1762627356489],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client\";\nimport { App } from \"./App.tsx\";\nimport { QueryProvider } from \"./providers/QueryProvider.tsx\";\n\nconst root = createRoot(document.getElementById(\"root\")!);\nroot.render(\n \n \n \n);\n",[],[297,416],[297],{"_102":425,"_95":426,"_152":427,"_154":-5,"_155":137,"_156":428,"_158":159,"_104":429,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_166":430,"_98":439},"cc378ace-bcd0-11f0-939e-42dde27851f2","shared","cc378bd2-bcd0-11f0-939e-42dde27851f2",4,["D",1762626541385],[431],{"_102":432,"_95":222,"_152":433,"_154":427,"_155":137,"_156":434,"_158":159,"_104":435,"_99":32,"_161":198,"_163":436,"_164":22,"_165":-5,"_166":437,"_98":438},"ccf12b46-bcd0-11f0-8f99-42dde27851f2","ccf12c9a-bcd0-11f0-8f99-42dde27851f2",30,["D",1762626542438],"/**\n * FlipDot Content Server API Types\n * Implements types from CONTENT_SERVER_SPEC.md\n */\n\n/**\n * A single frame of display content\n */\nexport interface Frame {\n /** Base64-encoded packed bit data (little-endian) */\n data_b64: string;\n /** Frame width in pixels */\n width: number;\n /** Frame height in pixels */\n height: number;\n /** Duration to display frame in milliseconds (null = static) */\n duration_ms?: number | null;\n /** Optional metadata for debugging/logging */\n metadata?: Record;\n}\n\n/**\n * Playback mode configuration\n */\nexport interface PlaybackMode {\n /** Whether to loop the animation */\n loop?: boolean;\n /** Number of times to loop (null = infinite) */\n loop_count?: number | null;\n /** Priority level (0-99, higher = more important) */\n priority?: number;\n /** Whether content can be interrupted by higher priority */\n interruptible?: boolean;\n}\n\n/**\n * Content package with frames and playback configuration\n */\nexport interface Content {\n /** Unique identifier for this content */\n content_id: string;\n /** Array of frames to display */\n frames: Frame[];\n /** Playback configuration */\n playback?: PlaybackMode;\n /** Optional metadata */\n metadata?: Record;\n}\n\n/**\n * Response status from content server\n */\nexport type ResponseStatus = \"updated\" | \"no_change\" | \"clear\";\n\n/**\n * Top-level response from GET /api/flipdot/content\n */\nexport interface ContentResponse {\n /** Status of the content update */\n status: ResponseStatus;\n /** Content to display (required when status=\"updated\") */\n content?: Content;\n /** Polling interval in milliseconds (minimum 1000) */\n poll_interval_ms: number;\n}\n",[],[426,222],[426],{"_102":441,"_95":442,"_152":443,"_154":-5,"_155":137,"_156":444,"_158":159,"_104":445,"_99":32,"_161":174,"_163":446,"_164":22,"_165":-5,"_166":447,"_98":448},"cce4a6b4-bcd0-11f0-a677-42dde27851f2",".vtignore","cce4a75e-bcd0-11f0-a677-42dde27851f2",27,["D",1762626542519],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor\n.local-storage\n",[],[442],{"_102":450,"_95":451,"_152":452,"_154":-5,"_155":137,"_156":453,"_158":159,"_104":454,"_99":32,"_161":174,"_163":455,"_164":22,"_165":-5,"_166":456,"_98":457},"cced1f2e-bcd0-11f0-a12f-42dde27851f2","CLAUDE.md","cced1ff6-bcd0-11f0-a12f-42dde27851f2",29,["D",1762626542575],"# FlipDot Content Server - AI Agent Guidelines\n\nYou are working on the **FlipDot Content Server**, a Val Town project that serves pre-rendered content to a FlipDot display driver running on a Raspberry Pi.\n\n## Project Overview\n\nThis server implements the **FlipDot Content Server API v2.0** specified in [CONTENT_SERVER_SPEC.md](./CONTENT_SERVER_SPEC.md). The driver polls this server for content, and the server is responsible for:\n\n- Rendering text, animations, and graphics into frames\n- Encoding frames in packed bit format (base64)\n- Managing content display logic (what to show when)\n- Handling authentication\n- Responding to polling requests\n\n**Key Architecture Principle:** The server does ALL rendering. The driver is minimal and only handles display queue management, timing, and hardware communication.\n\n### Display Specifications\n\n- **Dimensions:** 28×14 pixels (two 28×7 flipdot modules stacked vertically)\n- **Module Layout:** `[[1], [2]]` (stacked vertically)\n- **Pixel Format:** Binary (on/off), packed little-endian, base64-encoded\n- **Update Method:** Polling (driver polls every 30s by default)\n\n## Required Reading\n\n**BEFORE implementing any features, read:**\n\n1. **[CONTENT_SERVER_SPEC.md](./CONTENT_SERVER_SPEC.md)** - Complete API specification\n - Section 2: API Endpoints (polling endpoint is required)\n - Section 3: Data Models (ContentResponse, Content, Frame, PlaybackMode)\n - Section 4: Frame Data Format (packed bit encoding)\n - Section 5: Security (authentication requirements)\n\n2. **Key Spec Sections:**\n - **Section 3.1** - ContentResponse structure (`status`, `content`, `poll_interval_ms`)\n - **Section 3.3** - Frame structure and `data_b64` encoding\n - **Section 4** - Packed bit format (little-endian, row-major)\n - **Example responses** - Section 8.2\n\n## Project-Specific Guidelines\n\n### 1. API Implementation\n\n**Required Endpoint:**\n\n```ts\n// GET /api/flipdot/content\n// Returns: ContentResponse JSON\nexport default async function (req: Request) {\n // 1. Validate authentication\n // 2. Determine what content to show\n // 3. Render content to frames\n // 4. Return ContentResponse\n}\n```\n\n**Authentication:**\n\n- Check for `X-API-Key` header (or `Authorization: Bearer` token)\n- API key stored in environment variable: `Deno.env.get('FLIPDOT_API_KEY')`\n- Return `401 Unauthorized` if missing/invalid\n- Return `403 Forbidden` if insufficient permissions\n\n**Response Structure:**\n\n```ts\ninterface ContentResponse {\n status: \"updated\" | \"no_change\" | \"clear\";\n content?: Content; // Required when status=\"updated\"\n poll_interval_ms: number; // >= 1000\n}\n```\n\n### 2. Frame Rendering\n\n**Critical:** Frames must use packed bit format (see spec Section 4).\n\n**Reference Implementation Pattern:**\n\n```ts\n// Helper function to pack bits (little-endian)\nfunction packBitsLittleEndian(bits: number[]): Uint8Array {\n const byteArray = new Uint8Array(Math.ceil(bits.length / 8));\n for (let i = 0; i < bits.length; i++) {\n if (bits[i]) {\n byteArray[Math.floor(i / 8)] |= 1 << i % 8;\n }\n }\n return byteArray;\n}\n\n// Convert packed bytes to base64\nfunction bitsToBase64(bits: number[]): string {\n const packed = packBitsLittleEndian(bits);\n return btoa(String.fromCharCode(...packed));\n}\n\n// Create a frame\nfunction createFrame(\n width: number,\n height: number,\n bits: number[],\n durationMs?: number,\n) {\n return {\n data_b64: bitsToBase64(bits),\n width,\n height,\n duration_ms: durationMs ?? null,\n };\n}\n```\n\n**Bitmap Font Rendering:**\n\n- Use 5×7 or 6×8 bitmap fonts for text\n- Render text to bit array (row-major, left-to-right)\n- Consider using a font library or pre-defined character maps\n- Example: https://github.com/olikraus/u8g2/wiki/fntlistall (for reference)\n\n### 3. Content Types to Implement\n\n**Phase 1 (MVP):**\n\n- Static text messages\n- Clock display (updating every minute)\n- Simple animations (loading spinner, etc.)\n\n**Phase 2:**\n\n- Weather display\n- Scrolling text\n- Calendar/events\n- Notifications (via push)\n\n**Phase 3:**\n\n- Dynamic content routing (multiple content sources)\n- Content scheduling\n- Conditional display logic\n\n### 4. State Management\n\n**Important:** The server should be mostly stateless. The driver manages:\n\n- Content queue and priorities\n- Frame timing and advancement\n- Interruptions and resumptions\n\n**Server MAY maintain:**\n\n- Last shown content_id (to optimize `no_change` responses)\n- Content generation cache (to avoid re-rendering unchanged content)\n- Scheduled content calendar\n\n### 5. Val Town Specific Considerations\n\n**Storage:**\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\n\n// Cache rendered content\nawait blob.setJSON(\"flipdot:last_content\", contentResponse);\n\n// Get cached content\nconst cached = await blob.getJSON(\"flipdot:last_content\");\n```\n\n**Time-Based Content:**\n\n```ts\n// Use Deno's Date API\nconst now = new Date();\nconst hour = now.getHours();\nconst minute = now.getMinutes();\n\n// Generate clock content\nconst clockText = `${hour.toString().padStart(2, \"0\")}:${minute.toString().padStart(2, \"0\")}`;\n```\n\n**Cron for Updates:**\nIf you need to pre-compute content, use a cron val:\n\n```ts\n// Update cache every minute\nexport default async function () {\n const content = await generateClockContent();\n await blob.setJSON(\"flipdot:current_content\", content);\n}\n```\n\n### 6. Testing and Development\n\n**Test Responses:**\nUse these patterns to test incrementally:\n\n```ts\n// Minimal valid response (no content change)\nreturn Response.json({\n status: \"no_change\",\n poll_interval_ms: 30000,\n});\n\n// Static test frame (all pixels on)\nconst bits = new Array(28 * 14).fill(1);\nreturn Response.json({\n status: \"updated\",\n content: {\n content_id: \"test-pattern\",\n frames: [\n {\n data_b64: bitsToBase64(bits),\n width: 28,\n height: 14,\n duration_ms: null,\n },\n ],\n playback: {\n priority: 0,\n interruptible: true,\n },\n },\n poll_interval_ms: 30000,\n});\n```\n\n**Validation:**\n\n- All frames must be 28×14 pixels\n- Base64 must decode to at least `ceil(28 * 14 / 8) = 49` bytes\n- `poll_interval_ms` must be >= 1000\n- `content` required when `status=\"updated\"`\n\n**Local Testing:**\n\n```bash\n# Test the endpoint\ncurl -H \"X-API-Key: your-key\" https://your-val.val.run/api/flipdot/content\n```\n\n### 7. Project Structure Recommendation\n\n```\nval-server/\n├── backend/\n│ ├── index.ts # Main HTTP handler (polling endpoint)\n│ ├── auth.ts # Authentication logic\n│ ├── content/\n│ │ ├── clock.ts # Clock content generator\n│ │ ├── text.ts # Static text renderer\n│ │ ├── weather.ts # Weather content generator\n│ │ └── router.ts # Content routing logic\n│ └── rendering/\n│ ├── frame.ts # Frame creation utilities\n│ ├── font.ts # Bitmap font rendering\n│ └── bits.ts # Bit packing utilities\n├── shared/\n│ └── types.ts # Shared TypeScript types (Content, Frame, etc.)\n├── CONTENT_SERVER_SPEC.md # API specification\n└── CLAUDE.md # This file\n```\n\n### 8. Type Definitions\n\nCopy these from the spec into `shared/types.ts`:\n\n```ts\nexport interface Frame {\n data_b64: string;\n width: number;\n height: number;\n duration_ms?: number | null;\n metadata?: Record;\n}\n\nexport interface PlaybackMode {\n loop?: boolean;\n loop_count?: number | null;\n priority?: number;\n interruptible?: boolean;\n}\n\nexport interface Content {\n content_id: string;\n frames: Frame[];\n playback?: PlaybackMode;\n metadata?: Record;\n}\n\nexport type ResponseStatus = \"updated\" | \"no_change\" | \"clear\";\n\nexport interface ContentResponse {\n status: ResponseStatus;\n content?: Content;\n poll_interval_ms: number;\n}\n```\n\n### 9. Common Pitfalls\n\n**❌ Don't:**\n\n- Return content with dimensions other than 28×14\n- Use big-endian bit packing (must be little-endian)\n- Forget to base64 encode the packed bits\n- Return `poll_interval_ms` < 1000\n- Include `content` when `status` is `\"no_change\"` or `\"clear\"`\n- Hard-code secrets (use environment variables)\n\n**✅ Do:**\n\n- Validate authentication on every request\n- Use consistent `content_id` for the same logical content\n- Set appropriate `poll_interval_ms` (longer for static content)\n- Test bit packing with known patterns first\n- Log rendering errors for debugging\n- Cache rendered content when possible\n\n### 10. Security Checklist\n\n- [ ] API key validated on every request\n- [ ] API key stored in environment variable\n- [ ] No secrets in code or logs\n- [ ] Frame size limits enforced (max 1000 frames, 5MB total)\n- [ ] Input validation on any user-provided content\n- [ ] CORS headers set appropriately (if accessed from web)\n\n---\n\n## Val Town Standard Guidelines\n\nThe content below is standard Val Town guidance. See above for project-specific requirements.\n\n---\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious operations)\n- Follow modern ES6+ conventions and functional programming practices if possible\n\n## Types of triggers\n\n### 1. HTTP Trigger\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- Example structure:\n\n```ts\nexport default async function (req: Request) {\n return new Response(\"Hello World\");\n}\n```\n\nFiles that are HTTP triggers have http in their name like `foobar.http.tsx`\n\n### 2. Cron Triggers\n\n- Run on a schedule\n- Use cron expressions for timing\n- Example structure:\n\n```ts\nexport default async function () {\n // Scheduled task code\n}\n```\n\nFiles that are Cron triggers have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Triggers\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n // Process email\n}\n```\n\nFiles that are Email triggers have email in their name like `foobar.email.tsx`\n\n## Val Town Standard Libraries\n\nVal Town provides several hosted services and utility functions.\n\n### Blob Storage\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\nawait blob.setJSON(\"myKey\", { hello: \"world\" });\nlet blobDemo = await blob.getJSON(\"myKey\");\nlet appKeys = await blob.list(\"app_\");\nawait blob.delete(\"myKey\");\n```\n\n### SQLite\n\n```ts\nimport { sqlite } from \"https://esm.town/v/stevekrouse/sqlite\";\nconst TABLE_NAME = \"todo_app_users_2\";\n// Create table - do this before usage and change table name when modifying schema\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL\n)`);\n// Query data\nconst result = await sqlite.execute(\n `SELECT * FROM ${TABLE_NAME} WHERE id = ?`,\n [1],\n);\n```\n\nNote: When changing a SQLite table's schema, change the table's name (e.g., add \\_2 or \\_3) to create a fresh table.\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [{ role: \"user\", content: \"Say hello in a creative way\" }],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n### Email\n\n```ts\nimport { email } from \"https://esm.town/v/std/email\";\n// By default emails the owner of the val\nawait email({\n subject: \"Hi\",\n text: \"Hi\",\n html: \"

Hi

\",\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport {\n parseProject,\n readFile,\n serveFile,\n} from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", (c) => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", (c) => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's _extremely importing_ to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `

`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `` unless otherwise specified\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:**\n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n",[],[451],{"_102":459,"_95":460,"_152":461,"_154":-5,"_155":137,"_156":462,"_158":159,"_104":463,"_99":32,"_161":174,"_163":464,"_164":22,"_165":-5,"_166":465,"_98":466},"ccdde9d2-bcd0-11f0-a12f-42dde27851f2","CONTENT_SERVER_SPEC.md","ccddebee-bcd0-11f0-a12f-42dde27851f2",26,["D",1762626542441],"# FlipDot Content Server API Specification v2.0\n\n**Status:** Draft\n**Last Updated:** 2025-11-05\n**Protocol Version:** 2.0\n\n## 1. Overview\n\n### 1.1 Purpose\n\nThis document specifies the HTTP API that a content server must implement to provide content to the FlipDot driver. The driver is a lightweight client that polls for content and displays it on physical flipdot hardware.\n\n### 1.2 Architecture\n\n```\nContent Server (Stateless)\n ↓ HTTP/JSON (Poll)\nDriver (Raspberry Pi)\n ↓ Serial\nFlipDot Hardware\n```\n\nThe content server is responsible for:\n- Rendering content into frames\n- Responding to polling requests\n- Optionally pushing high-priority content\n\nThe driver is responsible for:\n- Polling the content server\n- Managing the display queue and priorities\n- Timing frame transitions\n- Communicating with hardware\n\n### 1.3 Design Principles\n\n- **Stateless Server:** The server does not track driver state\n- **Client-Driven Polling:** The driver controls polling frequency\n- **Push Optional:** Server can optionally push urgent content\n- **Pre-Rendered:** All rendering happens server-side\n- **Binary Efficient:** Frames use packed bit format\n\n## 2. API Endpoints\n\n### 2.1 Content Polling Endpoint (Required)\n\n**Endpoint:** `GET {poll_endpoint}`\n**Purpose:** Driver polls this endpoint to fetch current content\n\n#### 2.1.1 Request\n\n**Method:** `GET`\n\n**Headers:**\n```\nUser-Agent: FlipDot-Driver/2.0\nContent-Type: application/json\n```\n\n**Authentication Headers (choose one):**\n```\nAuthorization: Bearer {token}\n```\nOR\n```\n{header_name}: {api_key}\n```\n(Default header_name: `X-API-Key`)\n\n**Query Parameters:** None required\n\n#### 2.1.2 Response\n\n**Status Codes:**\n- `200 OK` - Content returned successfully\n- `401 Unauthorized` - Authentication failed\n- `403 Forbidden` - Insufficient permissions\n- `404 Not Found` - Endpoint not found\n- `500 Internal Server Error` - Server error\n\n**Content-Type:** `application/json`\n\n**Body:** ContentResponse object (see Section 3)\n\n**Example:**\n```json\n{\n \"status\": \"updated\",\n \"content\": {\n \"content_id\": \"clock-12:00:00\",\n \"frames\": [\n {\n \"data_b64\": \"AQIDBAUGBwgJ\",\n \"width\": 56,\n \"height\": 14,\n \"duration_ms\": 1000\n }\n ],\n \"playback\": {\n \"loop\": false,\n \"priority\": 0,\n \"interruptible\": true\n }\n },\n \"poll_interval_ms\": 30000\n}\n```\n\n#### 2.1.3 Timing Guarantees\n\n- Server SHOULD respond within 10 seconds (driver default timeout)\n- Server MAY use long-polling techniques\n- Server SHOULD set appropriate `poll_interval_ms` based on content update frequency\n\n### 2.2 Push Notification Endpoint (Optional)\n\n**Endpoint:** `POST http://{driver_host}:{push_port}/`\n**Purpose:** Server pushes high-priority content directly to driver\n\n**Note:** This endpoint is implemented by the driver, not the server. The server acts as a client to push urgent content.\n\n#### 2.2.1 Request\n\n**Method:** `POST`\n\n**Headers:**\n```\nContent-Type: application/json\n```\n\n**Authentication Headers (must match driver config):**\n```\n{header_name}: {api_key}\n```\nOR\n```\nAuthorization: Bearer {token}\n```\n\n**Body:** Content object (see Section 3.3)\n\n**Example:**\n```json\n{\n \"content_id\": \"urgent-alert\",\n \"frames\": [\n {\n \"data_b64\": \"AQIDBAUGBwgJ\",\n \"width\": 56,\n \"height\": 14,\n \"duration_ms\": 5000\n }\n ],\n \"playback\": {\n \"priority\": 99,\n \"interruptible\": false\n }\n}\n```\n\n#### 2.2.2 Response\n\n**Status Codes:**\n- `200 OK` - Content accepted\n- `401 Unauthorized` - Authentication failed\n- `413 Payload Too Large` - Request exceeds max_request_size\n- `400 Bad Request` - Invalid JSON or validation error\n- `500 Internal Server Error` - Driver error\n\n**Body:**\n```json\n{\n \"status\": \"accepted\"\n}\n```\n\n#### 2.2.3 Health Check\n\n**Endpoint:** `GET http://{driver_host}:{push_port}/health`\n**Response:**\n```json\n{\n \"status\": \"ok\"\n}\n```\n\n## 3. Data Models\n\n### 3.1 ContentResponse\n\nThe top-level response from the polling endpoint.\n\n```typescript\ninterface ContentResponse {\n status: \"updated\" | \"no_change\" | \"clear\";\n content?: Content;\n poll_interval_ms: number;\n}\n```\n\n**Fields:**\n\n| Field | Type | Required | Constraints | Description |\n|-------|------|----------|-------------|-------------|\n| `status` | enum | Yes | See below | Response status code |\n| `content` | Content | Conditional | Required if status=\"updated\" | Content to display |\n| `poll_interval_ms` | integer | Yes | >= 1000 | Milliseconds until next poll |\n\n**Status Values:**\n\n| Status | Meaning | Content Field |\n|--------|---------|---------------|\n| `updated` | New content available | Required |\n| `no_change` | Keep displaying current content | Omit |\n| `clear` | Clear the display | Omit |\n\n**Validation Rules:**\n- If `status` is `\"updated\"`, `content` MUST be present\n- If `status` is `\"no_change\"` or `\"clear\"`, `content` MUST be absent\n- `poll_interval_ms` MUST be at least 1000 (1 second)\n\n### 3.2 Content\n\nA sequence of frames with playback configuration.\n\n```typescript\ninterface Content {\n content_id: string;\n frames: Frame[];\n playback?: PlaybackMode;\n metadata?: object;\n}\n```\n\n**Fields:**\n\n| Field | Type | Required | Constraints | Description |\n|-------|------|----------|-------------|-------------|\n| `content_id` | string | Yes | Non-empty | Unique identifier for this content |\n| `frames` | Frame[] | Yes | 1-1000 frames | Array of frames to display |\n| `playback` | PlaybackMode | No | See below | Playback configuration |\n| `metadata` | object | No | Max 10KB JSON | Optional metadata for debugging |\n\n**Validation Rules:**\n- `frames` MUST contain at least 1 frame\n- `frames` MUST contain at most 1000 frames\n- All frames MUST have identical `width` and `height`\n- Total size of all frame data plus metadata MUST NOT exceed 5MB\n- If `metadata` is present, JSON-encoded size MUST NOT exceed 10KB\n\n### 3.3 Frame\n\nA single image to display.\n\n```typescript\ninterface Frame {\n data_b64: string;\n width: number;\n height: number;\n duration_ms?: number | null;\n metadata?: object;\n}\n```\n\n**Fields:**\n\n| Field | Type | Required | Constraints | Description |\n|-------|------|----------|-------------|-------------|\n| `data_b64` | string | Yes | Valid base64 | Base64-encoded packed bit data |\n| `width` | integer | Yes | > 0 | Frame width in pixels |\n| `height` | integer | Yes | > 0 | Frame height in pixels |\n| `duration_ms` | integer/null | No | >= 0 or null | Display duration (null = indefinite) |\n| `metadata` | object | No | Max 10KB JSON | Optional metadata |\n\n**Validation Rules:**\n- `data_b64` MUST be valid base64 encoding\n- Decoded data MUST be at least `ceil(width * height / 8)` bytes\n- `width` and `height` MUST match display dimensions (validated by driver)\n- `duration_ms` of `null` or `0` means display indefinitely\n- If `metadata` is present, JSON-encoded size MUST NOT exceed 10KB\n\n### 3.4 PlaybackMode\n\nConfiguration for how content should be played.\n\n```typescript\ninterface PlaybackMode {\n loop?: boolean;\n loop_count?: number | null;\n priority?: number;\n interruptible?: boolean;\n}\n```\n\n**Fields:**\n\n| Field | Type | Required | Default | Constraints | Description |\n|-------|------|----------|---------|-------------|-------------|\n| `loop` | boolean | No | false | - | Whether to loop frames |\n| `loop_count` | integer/null | No | null | >= 1, requires loop=true | Number of loops (null = infinite) |\n| `priority` | integer | No | 0 | 0-99 | Priority level |\n| `interruptible` | boolean | No | true | - | Can be interrupted by higher priority |\n\n**Priority Levels:**\n- **0-9:** Normal content (clock, weather, ambient)\n- **10-98:** Notifications (doorbell, messages, alerts)\n- **99:** Urgent/emergency alerts\n\n**Validation Rules:**\n- `loop_count` can only be set if `loop` is `true`\n- `priority` MUST be between 0 and 99 inclusive\n\n## 4. Frame Data Format\n\n### 4.1 Packed Bit Format\n\nFrames use a packed binary format for efficiency:\n\n1. **Bit Ordering:** Little-endian (LSB first)\n2. **Packing Direction:** Row-by-row, left-to-right\n3. **Padding:** Zero-padded to byte boundary\n4. **Encoding:** Base64\n\n### 4.2 Format Specification\n\nGiven a frame of `width × height` pixels:\n\n1. Flatten pixels into a 1D array: row-major order (left-to-right, top-to-bottom)\n2. Pack bits into bytes using little-endian bit order\n3. Total bytes = `ceil(width × height / 8)`\n4. Encode bytes as base64\n\n**Bit Position Formula:**\n```\nbyte_index = pixel_index / 8\nbit_position = pixel_index % 8\nbit_value = (byte[byte_index] >> bit_position) & 1\n```\n\n### 4.3 Example\n\n**Display:** 3×2 pixels\n\n```\nVisual: Pixel Array: Bit Array:\n1 0 1 [1, 0, 1, [1, 0, 1, 0, 1, 1, 0, 0]\n0 1 1 0, 1, 1]\n\nByte 0: 0b00110101 = 0x35\n\nBase64: \"NQ==\"\n```\n\n**Python Generation:**\n```python\nimport base64\n\ndef pack_bits_little_endian(bits):\n \"\"\"Pack array of bits into bytes (little-endian).\"\"\"\n byte_array = bytearray((len(bits) + 7) // 8)\n for i, bit in enumerate(bits):\n if bit:\n byte_array[i // 8] |= 1 << (i % 8)\n return bytes(byte_array)\n\nbits = [1, 0, 1, 0, 1, 1, 0, 0]\npacked = pack_bits_little_endian(bits)\nb64 = base64.b64encode(packed).decode()\n# Result: \"NQ==\"\n```\n\n## 5. Security\n\n### 5.1 Authentication\n\nThe server MUST implement one of the following authentication methods:\n\n#### 5.1.1 Bearer Token\n\n```\nAuthorization: Bearer {token}\n```\n\n- Server validates token on every request\n- Return `401 Unauthorized` if invalid\n- Token configured in driver via `auth.token`\n\n#### 5.1.2 API Key\n\n```\n{header_name}: {api_key}\n```\n\n- Default header name: `X-API-Key`\n- Configurable via `auth.header_name`\n- Server validates key on every request\n- Return `401 Unauthorized` if invalid\n- Key configured in driver via `auth.key`\n\n### 5.2 Content Limits\n\nThe server SHOULD respect these limits to prevent resource exhaustion:\n\n| Limit | Value | Purpose |\n|-------|-------|---------|\n| Max frames per content | 1000 | Prevent memory exhaustion |\n| Max total bytes | 5 MB | Prevent memory exhaustion |\n| Max metadata per item | 10 KB | Prevent metadata abuse |\n| Max push request size | 10 MB | Prevent network abuse |\n\n**Note:** These limits are enforced by the driver's validation. Content exceeding limits will be rejected.\n\n### 5.3 Rate Limiting\n\nThe server MAY implement rate limiting. Recommended approach:\n\n- Return `429 Too Many Requests` if rate limit exceeded\n- Include `Retry-After` header with seconds to wait\n- Driver will apply exponential backoff on errors\n\n### 5.4 HTTPS\n\nThe server SHOULD use HTTPS in production to protect:\n- Authentication credentials\n- Content data\n- Polling patterns (privacy)\n\n## 6. Behavior Specifications\n\n### 6.1 Polling Behavior\n\n**Driver Side:**\n1. Driver polls at intervals specified by `poll_interval_ms`\n2. On error, driver applies exponential backoff: 1s, 2s, 4s, 8s... up to 5min\n3. Driver sets `last_poll_time` at start of request (even if it fails)\n4. Driver includes request timeout (default 10s)\n\n**Server Side:**\n1. Server responds with current appropriate content\n2. Server sets `poll_interval_ms` based on expected update frequency\n3. Server may return `no_change` to reduce bandwidth\n4. Server may use cache headers (driver respects them)\n\n### 6.2 Content Updates\n\n**New Content:**\n```json\n{\n \"status\": \"updated\",\n \"content\": { \"content_id\": \"new-123\", ... }\n}\n```\n\n**No Change:**\n```json\n{\n \"status\": \"no_change\",\n \"poll_interval_ms\": 30000\n}\n```\n\n**Clear Display:**\n```json\n{\n \"status\": \"clear\",\n \"poll_interval_ms\": 10000\n}\n```\n\n### 6.3 Content Replacement\n\nIf the server returns content with the same `content_id` as currently playing content:\n- Driver MAY replace the content in-place\n- Driver attempts to preserve current frame index\n- Useful for live updates (e.g., updating clock without restart)\n\n### 6.4 Priority and Interruptions\n\n**Priority Queue (Driver Side):**\n1. Higher priority content interrupts lower priority (if interruptible)\n2. Interrupted content pauses and resumes when interruption completes\n3. Queue maintains priority order (highest first)\n4. Max 50 items in queue, 10 interrupted items\n\n**Server Recommendations:**\n- Use priority 0-9 for ambient content (clock, weather)\n- Use priority 10+ for notifications\n- Use priority 99 only for urgent alerts\n- Set `interruptible: false` for critical messages\n\n### 6.5 Frame Timing\n\n**Duration Behavior:**\n- `duration_ms > 0`: Frame displays for exactly this duration\n- `duration_ms = 0` or `null`: Frame displays indefinitely\n- Timing pauses during interruptions\n- Timing resumes when content is un-paused\n\n**Loop Behavior:**\n- `loop: false`: Play frames once, then complete\n- `loop: true, loop_count: null`: Loop indefinitely\n- `loop: true, loop_count: N`: Loop N times, then complete\n\n## 7. Error Handling\n\n### 7.1 HTTP Errors\n\n| Status Code | Driver Behavior |\n|-------------|-----------------|\n| 401/403 | Log auth error, apply backoff |\n| 404 | Log endpoint error, apply backoff |\n| 429 | Apply backoff (respect Retry-After) |\n| 500+ | Log server error, apply backoff |\n| Timeout | Apply backoff |\n| Network error | Apply backoff |\n\n### 7.2 Validation Errors\n\nIf driver receives invalid data:\n1. Log detailed validation error\n2. Reject the content\n3. Apply error backoff\n4. Continue displaying previous content (if `error_fallback: keep_last`)\n\n### 7.3 Fallback Behavior\n\nConfigured by driver's `error_fallback` setting:\n\n| Mode | Behavior |\n|------|----------|\n| `keep_last` | Keep displaying last successful content |\n| `blank` | Clear display on error |\n| `error_message` | Show error state (future) |\n\n## 8. Testing\n\n### 8.1 Server Compliance Checklist\n\n- [ ] GET endpoint returns valid ContentResponse JSON\n- [ ] Authentication validates bearer token or API key\n- [ ] Returns 401 on invalid authentication\n- [ ] All frames in Content have matching dimensions\n- [ ] Respects content size limits (1000 frames, 5MB total)\n- [ ] Base64 data is valid and correct size\n- [ ] status=\"updated\" always includes content\n- [ ] status=\"no_change\"/\"clear\" never includes content\n- [ ] poll_interval_ms is at least 1000\n- [ ] Priority values are 0-99\n\n### 8.2 Example Valid Responses\n\n**Minimal Response:**\n```json\n{\n \"status\": \"no_change\",\n \"poll_interval_ms\": 30000\n}\n```\n\n**Static Image:**\n```json\n{\n \"status\": \"updated\",\n \"content\": {\n \"content_id\": \"hello-world\",\n \"frames\": [{\n \"data_b64\": \"AQIDBAUGBwgJ\",\n \"width\": 56,\n \"height\": 14,\n \"duration_ms\": null\n }]\n },\n \"poll_interval_ms\": 60000\n}\n```\n\n**Animation:**\n```json\n{\n \"status\": \"updated\",\n \"content\": {\n \"content_id\": \"loading-spinner\",\n \"frames\": [\n {\n \"data_b64\": \"AQIDBA==\",\n \"width\": 8,\n \"height\": 8,\n \"duration_ms\": 100\n },\n {\n \"data_b64\": \"BQYHCA==\",\n \"width\": 8,\n \"height\": 8,\n \"duration_ms\": 100\n }\n ],\n \"playback\": {\n \"loop\": true\n }\n },\n \"poll_interval_ms\": 30000\n}\n```\n\n**High-Priority Notification:**\n```json\n{\n \"status\": \"updated\",\n \"content\": {\n \"content_id\": \"doorbell-ring\",\n \"frames\": [{\n \"data_b64\": \"ISEhISE=\",\n \"width\": 56,\n \"height\": 14,\n \"duration_ms\": 5000\n }],\n \"playback\": {\n \"priority\": 10,\n \"interruptible\": false\n }\n },\n \"poll_interval_ms\": 30000\n}\n```\n\n## 9. OpenAPI Schema\n\nSee [openapi.yaml](./openapi.yaml) for machine-readable API specification.\n\n## 10. Versioning\n\n**Current Version:** 2.0\n\n**Version History:**\n- **2.0** (2025-11-05): New architecture with content server separation\n- **1.0** (Legacy): Monolithic driver with built-in modes\n\n**Breaking Changes in 2.0:**\n- Content must be pre-rendered by server\n- Packed bit format instead of live rendering\n- Removed display modes from driver\n- Added priority queue system\n\n## 11. References\n\n- [FlipDot Driver README](./README.md)\n- [Driver Implementation](./flipdot/driver/)\n- [Data Models](./flipdot/driver/models.py)\n- [Example Content Generator](./examples/generate_content.py)\n\n## Appendix A: ABNF Grammar\n\n```abnf\nContentResponse = %s\"{\" *WSP\n %s\"\\\"status\\\"\" *WSP \":\" *WSP Status *WSP \",\"\n [ %s\"\\\"content\\\"\" *WSP \":\" *WSP Content *WSP \",\" ]\n %s\"\\\"poll_interval_ms\\\"\" *WSP \":\" *WSP Integer\n *WSP %s\"}\"\n\nStatus = %s\"\\\"updated\\\"\" / %s\"\\\"no_change\\\"\" / %s\"\\\"clear\\\"\"\n\nContent = %s\"{\" *WSP\n %s\"\\\"content_id\\\"\" *WSP \":\" *WSP String *WSP \",\"\n %s\"\\\"frames\\\"\" *WSP \":\" *WSP \"[\" Frame *( \",\" Frame ) \"]\" *WSP\n [ \",\" *WSP %s\"\\\"playback\\\"\" *WSP \":\" *WSP PlaybackMode ]\n [ \",\" *WSP %s\"\\\"metadata\\\"\" *WSP \":\" *WSP Object ]\n *WSP %s\"}\"\n\nFrame = %s\"{\" *WSP\n %s\"\\\"data_b64\\\"\" *WSP \":\" *WSP String *WSP \",\"\n %s\"\\\"width\\\"\" *WSP \":\" *WSP Integer *WSP \",\"\n %s\"\\\"height\\\"\" *WSP \":\" *WSP Integer\n [ \",\" *WSP %s\"\\\"duration_ms\\\"\" *WSP \":\" *WSP ( Integer / Null ) ]\n [ \",\" *WSP %s\"\\\"metadata\\\"\" *WSP \":\" *WSP Object ]\n *WSP %s\"}\"\n\nPlaybackMode = %s\"{\" *WSP\n [ %s\"\\\"loop\\\"\" *WSP \":\" *WSP Boolean ]\n [ \",\" *WSP %s\"\\\"loop_count\\\"\" *WSP \":\" *WSP ( Integer / Null ) ]\n [ \",\" *WSP %s\"\\\"priority\\\"\" *WSP \":\" *WSP Integer ]\n [ \",\" *WSP %s\"\\\"interruptible\\\"\" *WSP \":\" *WSP Boolean ]\n *WSP %s\"}\"\n```\n\n## Appendix B: Conversion Formulas\n\n### Bits to Bytes\n```\nbytes_needed = ceil(width × height / 8)\n```\n\n### Pixel to Bit Index\n```\nbit_index = (row × width) + col\n```\n\n### Bit Index to Byte Position\n```\nbyte_index = bit_index / 8\nbit_position = bit_index % 8\n```\n\n### Extract Bit Value\n```\nbit_value = (byte[byte_index] >> bit_position) & 1\n```\n\n---\n\n**Document Status:** Ready for Implementation\n**Feedback:** Please open issues at the project repository\n",[],[460],{"_102":468,"_95":469,"_152":470,"_154":-5,"_155":137,"_156":471,"_158":159,"_104":472,"_99":290,"_161":174,"_163":473,"_164":22,"_165":-5,"_166":474,"_98":475},"30947bfc-bcd7-11f0-a7c0-42dde27851f2","deno.json","cc932104-bcd0-11f0-8f99-42dde27851f2",75,["D",1762629286730],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/98f62cee78e85bfc47c62ed703777c6bc8794f1c/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"tasks\": {\n \"dev\": \"deno run --allow-net --allow-read --allow-write --allow-env --allow-import dev.ts\",\n \"fmt\": \"deno fmt\",\n \"lint\": \"deno lint\",\n \"check\": \"deno check --all --allow-import **/*.ts **/*.tsx\"\n },\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": true,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"include\": [\"deno:/https/esm.town/**/*\"],\n \"rules\": {\n \"exclude\": [\"no-explicit-any\"]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[],[469],{"_102":477,"_95":478,"_152":479,"_154":-5,"_155":137,"_156":480,"_158":159,"_104":481,"_99":428,"_161":198,"_163":482,"_164":22,"_165":-5,"_166":483,"_98":484},"1271db54-bcd4-11f0-a33b-42dde27851f2","dev.ts","cc8b2f80-bcd0-11f0-bf01-42dde27851f2",60,["D",1762627947695],"#!/usr/bin/env -S deno run --allow-net --allow-read --allow-write --allow-env --allow-import\n\n/**\n * Local development server\n * Run with: deno run --allow-net --allow-read --allow-write --allow-env --allow-import dev.ts\n * Or: chmod +x dev.ts && ./dev.ts\n */\n\nimport { load } from \"https://deno.land/std@0.224.0/dotenv/mod.ts\";\nimport app from \"./backend/index.ts\";\n\n// Load .env file from parent directory\nconst env = await load({ envPath: \"../.env\", export: true });\n\nconst PORT = 8000;\n\n// Get the fetch handler from the Hono app\nconst handler = app.fetch.bind(app);\n\nconsole.log(`\n╔═══════════════════════════════════════════════════════════════╗\n║ FlipDot Content Server - Local Development ║\n╚═══════════════════════════════════════════════════════════════╝\n\nServer running at: http://localhost:${PORT}\n\nEndpoints:\n GET / - Server info\n GET /health - Health check (no auth)\n GET /api/flipdot/content - Content endpoint (requires auth)\n\nEnvironment:\n Storage: Local filesystem (./.local-storage/)\n Auth: Set FLIPDOT_API_KEY env variable\n\nTest commands:\n curl http://localhost:${PORT}/health\n curl -H \"X-API-Key: test\" http://localhost:${PORT}/api/flipdot/content\n\nPress Ctrl+C to stop\n═══════════════════════════════════════════════════════════════\n`);\n\n// Set default API key for local dev if not set\nif (!Deno.env.get(\"FLIPDOT_API_KEY\")) {\n console.error(\"⚠️ No FLIPDOT_API_KEY set\");\n}\n\nDeno.serve({ port: PORT }, handler);\n",[],[478],{"_102":486,"_95":487,"_152":488,"_154":-5,"_155":137,"_156":489,"_158":159,"_104":490,"_99":183,"_161":491,"_163":492,"_164":22,"_165":493,"_166":494,"_98":495},"0ba0ced2-bcd1-11f0-a25d-42dde27851f2","httpEndpoint.ts","036ffad0-bcd1-11f0-a8c9-42dde27851f2",37,["D",1762626647767],"http","import app from \"./backend/index.ts\";\n\nexport default app.fetch;\n","dmcd-flipdot",[],[487],"files",[149,168,179,186,192,202,211,220,230,237,246,255,265,274,284,295,301,308,317,326,335,345,352,362,369,379,386,396,405,414,424,431,440,449,458,467,476,485],"counts",{"_500":32,"_501":290,"_502":32,"_503":504},"pulls","branches","forks","envVars",{"_505":183,"_506":32},"count","emptyCount","contents",[509,512,515,518,521,524,527,530,533,536],{"_102":150,"_95":151,"_152":153,"_154":-5,"_155":137,"_156":157,"_158":159,"_104":510,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_98":511},["D",1762626541185],[151],{"_102":180,"_95":181,"_152":182,"_154":-5,"_155":137,"_156":183,"_158":159,"_104":513,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_98":514},["D",1762626541286],[181],{"_102":296,"_95":297,"_152":298,"_154":-5,"_155":137,"_156":290,"_158":159,"_104":516,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_98":517},["D",1762626541037],[297],{"_102":425,"_95":426,"_152":427,"_154":-5,"_155":137,"_156":428,"_158":159,"_104":519,"_99":32,"_161":162,"_163":-5,"_164":22,"_165":-5,"_98":520},["D",1762626541385],[426],{"_102":441,"_95":442,"_152":443,"_154":-5,"_155":137,"_156":444,"_158":159,"_104":522,"_99":32,"_161":174,"_163":446,"_164":22,"_165":-5,"_98":523},["D",1762626542519],[442],{"_102":450,"_95":451,"_152":452,"_154":-5,"_155":137,"_156":453,"_158":159,"_104":525,"_99":32,"_161":174,"_163":455,"_164":22,"_165":-5,"_98":526},["D",1762626542575],[451],{"_102":459,"_95":460,"_152":461,"_154":-5,"_155":137,"_156":462,"_158":159,"_104":528,"_99":32,"_161":174,"_163":464,"_164":22,"_165":-5,"_98":529},["D",1762626542441],[460],{"_102":468,"_95":469,"_152":470,"_154":-5,"_155":137,"_156":471,"_158":159,"_104":531,"_99":290,"_161":174,"_163":473,"_164":22,"_165":-5,"_98":532},["D",1762629286730],[469],{"_102":477,"_95":478,"_152":479,"_154":-5,"_155":137,"_156":480,"_158":159,"_104":534,"_99":428,"_161":198,"_163":482,"_164":22,"_165":-5,"_98":535},["D",1762627947695],[478],{"_102":486,"_95":487,"_152":488,"_154":-5,"_155":137,"_156":489,"_158":159,"_104":537,"_99":183,"_161":491,"_163":492,"_164":22,"_165":493,"_98":538},["D",1762626647767],[487],"upstreamProject","upstreamBranch","emptyEnvVars","isNew","flags",[],"routes/_app.x.$handle.$name.environment-variables",{"_93":94,"_95":96,"_100":547,"_503":552},{"_102":103,"_95":96,"_104":548,"_106":-5,"_107":22,"_108":109,"_110":111,"_112":-5,"_14":113,"_114":-5,"_115":22,"_116":-5,"_117":32,"_16":118,"_119":120,"_121":120,"_122":123,"_124":123,"_125":123,"_126":120,"_127":120,"_23":549,"_131":550,"_134":551,"_146":22},["D",1762350360767],{"_93":94,"_129":130},{"_93":94,"_133":130,"_14":113},{"_99":136,"_95":43,"_102":137,"_138":103,"_139":-5,"_140":-5,"_141":-5,"_142":-5,"_143":-5,"_144":96,"_145":94},[553,559,562],{"_554":555,"_104":556,"_557":-5,"_110":72,"_558":22},"key","FLIPDOT_PASSWORD",["D",1762627408097],"updatedAt","isEmpty",{"_554":560,"_104":561,"_557":-5,"_110":72,"_558":22},"FLIPDOT_API_KEY",["D",1762626910284],{"_554":563,"_104":564,"_557":-5,"_110":72,"_558":22},"IS_VALTOWN",["D",1762626710415],"actionData","errors"]

drewmcdonald

flipdot

Environment variables