apotheosys1982/chat-first-surface-shell

1. This repository is a standalone, static browser prototype for a “chat-first” assistant shell. The app is not a full backend service; the runtime surface is the HTML/CSS/JS bundle under assistants/chat-first-surface-shell/public, mirrored into dist/chat-first-surface-shell for deployment.

2. The entry point is a single-page browser app: public/index.html loads the shell script, styles, motion CSS, and supporting data files. Netlify is the publishing target, and the repo is structured so the source app directory is what gets deployed directly.

3. The main interactive subsystem is the chat shell itself, centered on the composer. The README makes clear that the composer is treated as the command line for the surface, and the shell is intentionally “chat-first” rather than a generic dashboard. This is the first screen and the primary control surface.

4. Artifact handling is a distinct routing boundary. The shell prioritizes “artifact commands” over natural-language answer-room routing, and registered artifacts open in a full-viewport artifact layer. That means command interpretation and artifact presentation are a separate path from ordinary chat responses.

5. Uploaded or imported files are quarantined rather than becoming trusted sources automatically. The presence of source-registry.js, state-events.js, project-state.js, and the “source inbox” planning/history files suggests a source-ingestion pipeline with explicit approval/state transitions instead of immediate activation.

6. State management appears to be split across a few small client-side modules: project-state.js for persisted shell state, state-events.js for state change events, and source-registry.js for tracking approved sources/artifacts. This suggests a lightweight evented state model rather than a server-backed store.

7. Rendering is decomposed into shell chrome, content area, and motion/transition concerns. The motion/ directory contains shared-element and view-transition CSS libraries plus motion tokens, indicating that view changes and full-viewport artifact transitions are a first-class UI concern rather than incidental styling.

8. There is explicit support for a fallback-capable “HTML-in-Canvas” or canvas document stage. The repository contains a validation script for this (validate-chat-first-html-canvas-stage.js) and associated planning/evaluation docs, implying the app can attempt native canvas-based document rendering when browser APIs allow it, but must report DOM fallback honestly when they do not.

9. The viewport and scrolling behavior are constrained as part of the product architecture. Multiple planning/checksum items reference viewport lock, scroll stability, chrome direction, and offscreen tray behavior, which indicates the shell is designed to stay vertically constrained on both mobile and desktop and avoid horizontal pan or clipped UI regions.

10. The build/deployment workflow is simple but tightly governed. tools/compile-chat-first-answer-pack.js produces public/compiled-answer-pack.js, tools/sync-chat-first-state.js keeps source and mirror state aligned, and the various validate-* scripts enforce shell, routing, ingestion, rendering, and checksum invariants. The checksums/, receipts/, and logs/ directories show an audit trail for these validation passes.

11. The repo also contains a substantial planning-and-handoff layer (docs/, receipts/, logs/, top-level PLANNING_*.md, HANDOFF_*.md). These files are not runtime subsystems, but they are part of the architecture process: they document design decisions for routing, premium UI, artifact lifecycle, and live evaluation protocols.

12. In deployment terms, the architecture is “source app + mirrored dist bundle + static host.” Local development uses Python’s built-in HTTP server, while production is Netlify. That means the critical boundary is not an API tier, but consistency between the source directory, the compiled answer pack, and the published mirror.