@peers-app/peers-ui 0.15.4 → 0.16.0

package/docs/getting-started.md

@@ -1,284 +0,0 @@
-# Peers UI Framework - Getting Started Guide
-
-## Overview
-
-The Peers UI Framework is a dynamic, package-based system that allows loading and rendering user-created UI components at runtime. It consists of two main systems working together: **Route Loading** and **UI Component Loading**.
-
-## Key Concepts
-
-### **Packages**
-- Self-contained bundles of code stored in the database
-- Each package can contain both route definitions and UI components
-- Packages have `routesBundleFileId` and `uiBundleFileId` fields
-
-### **Routes**  
-- Define which URLs map to which UI components
-- Support path matching, props validation, and conditional rendering
-- Registered globally and matched dynamically
-
-### **UI Components**
-- React components loaded on-demand from package bundles
-- Wrapped in error boundaries for safe loading
-- Support props validation with Zod schemas
-
-## System Architecture
-
-```mermaid
-graph TB
-    subgraph "Package Storage"
-        DB[(Database)]
-        PkgA[Package A<br/>routes + UI bundles]
-        PkgB[Package B<br/>routes + UI bundles]
-        DB --> PkgA
-        DB --> PkgB
-    end
-    
-    subgraph "Route System"
-        RL[routes-loader.ts]
-        WR[Window Route Registry]
-        RL --> WR
-    end
-    
-    subgraph "UI System"  
-        UL[ui-loader.tsx]
-        UR[UIRouter]
-        UC[UILoader] 
-        UL --> UR --> UC
-    end
-    
-    subgraph "Runtime"
-        APP[App Component]
-        TABS[TabsLayout]
-        ROUTER[Router Component]
-        APP --> TABS --> ROUTER
-    end
-    
-    PkgA --> RL
-    PkgB --> RL
-    WR --> UR
-    ROUTER --> UR
-```
-
-## Loading Sequence
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant RL as routes-loader
-    participant DB as Database
-    participant WR as Window Registry
-    participant UI as ui-loader
-    participant USER as User Navigation
-
-    Note over App,USER: 1. Application Startup
-    App->>RL: loadAllRoutes()
-    RL->>DB: Get packages with routesBundleFileId
-    DB-->>RL: Package list
-    
-    Note over RL,WR: 2. Routes Registration
-    loop For each package
-        RL->>DB: Download routes bundle code
-        DB-->>RL: Bundle JavaScript code
-        RL->>RL: Execute bundle via new Function()
-        RL->>WR: registerPeersUIRoute(routes)
-    end
-    
-    Note over USER,UI: 3. User Navigation
-    USER->>App: Navigate to /some-path
-    App->>UI: UIRouter({ path: '/some-path' })
-    UI->>WR: Find matching route
-    WR-->>UI: Route with peersUIId
-    
-    Note over UI,DB: 4. Component Loading
-    UI->>UI: Check if component cached
-    alt Component not cached
-        UI->>DB: Download UI bundle code
-        DB-->>UI: Component JavaScript code
-        UI->>UI: Execute bundle, register component
-    end
-    UI->>UI: Render component with error boundary
-    UI-->>App: React Component
-```
-
-## Route Registration Flow
-
-### 1. **Package Discovery**
-```typescript
-// routes-loader.ts finds packages with UI capabilities
-let packagesWithUI = await Packages().list({
-  disabled: { $ne: true },
-  routesBundleFileId: { $exists: true },
-});
-```
-
-### 2. **Route Bundle Execution**
-```typescript
-// Download and execute route bundle code
-const bundleCode = await rpcServerCalls.getFileContents(pkg.routesBundleFileId);
-const exportRoutes = (peerRoutes) => {
-  peerRoutes.routes.forEach(route => {
-    window.registerPeersUIRoute(route); // Register globally
-  });
-}
-const bundleFunction = new Function('exportRoutes', bundleCode);
-bundleFunction(exportRoutes);
-```
-
-### 3. **Route Matching**
-```typescript
-// UIRouter matches incoming paths against registered routes
-const allRoutes = window.getPeersUIRoutes();
-const matchingRoute = allRoutes.find(route => {
-  // Path matching (supports regex)
-  // Props validation  
-  // Conditional matching via isMatch()
-});
-```
-
-## UI Component Loading Flow
-
-### 1. **Component Discovery**
-```typescript
-// UIRouter delegates to UILoader with matched route
-return UILoader({ peersUIId: matchingRoute.peersUIId, props });
-```
-
-### 2. **Bundle Loading**
-```typescript
-// Download UI bundle if not cached
-const bundleCode = await rpcServerCalls.getFileContents(pkg.uiBundleFileId);
-const exportUIs = (peerUIs) => {
-  peerUIs.uis.forEach(ui => {
-    peersUIs[ui.peersUIId] = ui; // Cache component
-  });
-}
-const bundleFunction = new Function('exportUIs', bundleCode);
-bundleFunction(exportUIs);
-```
-
-### 3. **Component Rendering**
-```typescript
-// Render cached component with error boundary
-const Component = peersUI.content;
-return (
-  <UIErrorBoundary peersUIId={peersUIId}>
-    <Component {...props} />
-  </UIErrorBoundary>
-);
-```
-
-## Error Handling
-
-The framework provides comprehensive error handling:
-
-### **Route Loading Errors**
-- Invalid bundle code execution
-- Missing route bundle files
-- Network failures during download
-
-### **UI Component Errors**
-- Bundle loading failures with retry mechanism
-- Props validation errors with detailed feedback
-- Runtime component errors with error boundaries
-
-### **Error UI Examples**
-```typescript
-// Bundle Loading Error
-<div style={{ border: '2px solid #ff6b6b' }}>
-  <h3>Bundle Loading Error</h3>
-  <div>Package: {pkg.name}</div>
-  <button onClick={retry}>Retry Loading</button>
-</div>
-
-// Props Validation Error  
-<div>Props did not match schema</div>
-<pre>{JSON.stringify(validationError, null, 2)}</pre>
-```
-
-## Integration Points
-
-### **System Apps vs Package Apps**
-
-| System Apps | Package Apps |
-|-------------|--------------|
-| Built into peers-ui | Loaded from database |
-| Direct router integration | Dynamic route registration |
-| Immediate availability | Async loading required |
-| Examples: Tools, Assistants | Examples: Custom user apps |
-
-### **TabsLayout Integration**
-```typescript
-// System apps integrated directly
-const systemApps = [assistantsApp, toolsApp, workflowsApp];
-
-// Package apps discovered dynamically  
-const [packages] = useObservable(allPackages);
-const appPackages = packages.filter(p => !p.disabled && p.appNavs?.length);
-```
-
-### **Router Integration**
-```typescript
-// TabsLayout calls Router for content rendering
-const renderTabContent = (tab) => {
-  return <Router path={tab.path} />;
-};
-
-// Router attempts UIRouter before falling back to system routes
-const ui = UIRouter({ path, props: {}, uiCategory: 'screen' });
-if (ui) return ui;
-// ... fallback to system routes
-```
-
-## Development Workflow
-
-### **Creating a New Package App**
-
-1. **Create Route Bundle**: Define routes that map paths to component IDs
-2. **Create UI Bundle**: Implement React components with props validation
-3. **Package Registration**: Store bundles in database with proper file IDs
-4. **App Navigation**: Add app navigation metadata for tabs integration
-
-### **Package Bundle Structure**
-```javascript
-// Route Bundle (executed at startup)
-exportRoutes({
-  routes: [{
-    peersUIId: 'my-component-id',
-    path: '/my-app',
-    uiCategory: 'screen',
-    propsSchema: z.object({ id: z.string() }),
-    isMatch: (props, context) => true
-  }]
-});
-
-// UI Bundle (loaded on-demand)  
-exportUIs({
-  uis: [{
-    peersUIId: 'my-component-id',
-    content: MyReactComponent,
-    propsSchema: z.object({ id: z.string() })
-  }]
-});
-```
-
-## Performance Characteristics
-
-### **Optimizations**
-- **Lazy Loading**: UI bundles loaded only when needed
-- **Caching**: Components cached in memory after first load
-- **Bundle Splitting**: Routes and UI separated for faster startup
-- **Error Boundaries**: Component failures don't crash entire app
-
-### **Bundle Size Impact**
-- Small route bundles loaded at startup (fast)
-- Large UI bundles loaded on-demand (UX optimized)
-- Each package isolated (no dependency conflicts)
-
-## Next Steps
-
-- **[System Apps Guide](architecture/system-apps.md)** - Learn system app patterns
-- **[Router Patterns](architecture/router-patterns.md)** - Advanced routing techniques  
-- **[Component Library](components/component-library.md)** - Reusable UI components
-- **[Groups Implementation Example](examples/groups-implementation.md)** - Real-world implementation guide
-
-This framework enables a truly extensible application where users can create and share custom UI components while maintaining system stability and performance.

package/docs/knowledge.md

@@ -1,187 +0,0 @@
-### Scratchpad
-
-Implementation 
-- [x] Ability to add notes
-- [ ] Ability to paste raw markdown
-- [ ] Need to be able to mark up paragraphs (or just parts of notes) with metadata
-- [ ] turn task list items into distinct, top-level tasks
-- implement logical argument system
-  - [ ] classify and critique
-- implement PKS
-  - [ ] asdf
-
----
-
-### Key Components for Argument Breakdown System:
-
-
-1. **Premise Classification**
-- Explicit premises 
-  - Clearly stated and directly presented within the argument
-- Implicit premises 
-  - Not directly stated but is assumed or inferred by the audience to complete the argument. Implicit premises often rely on shared knowledge or common understanding to be recognized.
-
-2. **Inference & Conclusion Classification**
-- Deductive 
-  - Derived from deductive reasoning, where if the premises are true, the conclusion must be true.
-  - Guarantees the truth of the conclusion if the premises are true
-- Inductive 
-  - Generalizes from specific instances
-  - Based on inductive reasoning, where the conclusion is likely but not guaranteed, derived from specific observations.
-- Abductive 
-  - Involves finding the most plausible explanation for a set of observations, often used in hypothesis generation.
-  - Starts with an observation or set of observations and seeks the simplest and most likely explanation
-- Analogical 
-  - Drawn from analogical reasoning, where similarities between two situations lead to a conclusion about one based on the other.
-- Probabilistic 
-  - Involves conclusions that are expressed in terms of probability, often used in statistical reasoning.
-
-
-3. **Evidence Categorization**
-- Facts
-- Statistics
-- Examples (empirical or anecdotal)
-- Clearly define what constitutes empirical versus anecdotal evidence to avoid ambiguity.
-
-4. **Fallacy Detection**
-- Ad Hominem
-  - Attacking the person instead of the argument.
-- Straw Man
-  - Misrepresenting an argument to make it easier to attack.
-- Appeal to Ignorance
-  - Claiming something is true because it hasn't been proven false.
-- False Dilemma
-  - Presenting two options as the only possibilities.
-- Slippery Slope
-  - Arguing that a small step will lead to a chain of events resulting in a significant impact.
-- Circular Reasoning
-  - The conclusion is included in the premise.
-- Hasty Generalization
-  - Making a broad claim based on limited evidence.
-- Red Herring
-  - Introducing irrelevant information to distract from the main issue.
-- Appeal to Authority
-  - Believing a claim is true because an authority figure endorses it.
-- Post Hoc
-  - Assuming that because one event followed another, it was caused by it.
-
-### Notes:
-
-- Ensure the system can identify and handle contradictions within the premises or between the premises and the conclusion effectively.
-
-
-1. **Contextual Analysis:**
-- Incorporate a module to understand the context in which the argument is made. Context can influence the interpretation of premises and conclusions.
-- The context of the argument can result in wildly different outcomes
-
-2. **User Feedback Loop:**
-- Implement a feedback mechanism where users can validate or dispute the system's interpretation of the argument. This can help in refining the accuracy of the system over time.
-
-3. **Semantic Analysis:**
-- Use natural language processing to detect nuances in language that might affect the interpretation of premises and conclusions.
-
-4. **Source Credibility:**
-- Evaluate the credibility of sources cited in the argument. This can be crucial in assessing the reliability of the evidence presented.
-
-5. **Argument Strength Assessment:**
-- Develop a metric to assess the strength of the argument based on the robustness of the logical structure and the quality of evidence.
-
-6. **Multi-perspective Analysis:**
-- Allow for the analysis of arguments from multiple perspectives to understand how different viewpoints might interpret the same set of facts differently.
-
----
-
-
-**Note / Doc (Entry)**
-- This will be any entry from the user
-- Everything starts here
-- User's can "assert" that it is a "argument part"
-  - 
-
-**Data**
-- This is a critically different in that it is meant to be entered in a tabular format with statistical analysis applied
-  - gun data like deaths, incidents of self defense, etc. can be used to assert wildly different conclusions
-- Instead of being raw markdown it's tabular data
-- I _think_ everything else can just be markdown?
-
-Parts
-- Premises / Assumptions / Givens
-  - supporting data
-
-Data
-
-
-
---- 
-
-### Questions as starting point
-- the idea here is to move away from the "logical arguments" structure and into the "I have a question that I want answered"
-- potential forms:
-  - Question + accepted + alternate answers
-  - Jeopardy - I have an answer, what's the question
-  - ...
-- This would still have entry types
-  - observations / notes
-    - "this is how I do this"
-    - "this happened on this day"
-  - conclusions from data
-    - A / B test results
-
-The big pull for this is that it seems the most useful with real-world application.  At the same time, how many QA sites already exist (Stack overflow, Quora, Google in a way, etc.).  
-
-So I think I'm getting tangled up trying to marry a note-taking system to a logical argument system to a personal knowledge system (PKS).  
-
-Notes should absolutely be part of the system but the real goal here is to "help users perceive truth from untruth".  So the logical argument part should be front and center.  Also the PKS aspect of this seems like a direct extension of the logical argument system and appropriate to include.  Finally, remember I think this is a problem uniquely suited to LLMs which can act as a kind of compiler and greatly streamline and automate the process of formalizing one's thoughts on a give subject.  
-
-So the features are
-- Raw entries
-- logical arguments
-  - categorize paragraphs into
-    - Premise
-    - Inference
-  - Automatically highlight
-    - Inference type used
-    - Critical Assumptions 
-    - Fallacies 
-- personal knowledge system
-  - links
-  - search
-  - "workspace" which pulls on notes and LLM calls out unifying thread
-    - this is basically a "hub note" I think
-
-In some sense this is a PKS with the logical arguments kind of imposed on top. That actually sounds pretty good.  **So start with the notes (raw entries)**
-
-The UI for going from "raw entry" to classified argument parts is very key. Ideas:
-- Jupyter Notebook format
-  - raw entries have paragraphs.  Each paragraph is an atomic "raw entry".  
-  - The system adds metadata to the paragraph (Premise, Inference type, etc) as well as the "Notebook / Document"
-  - A sidebar can contain related content from other parts of the system
-    - This will often be auto-populated by the LLM using vector search
-    - It or a related sidebar can be populated by the user with atomic notes that the user wants to try to incorporate or just wants available as a reference.  
-
-- Workspace format
-  - A space with cards that can be dragged around and rearranged into hierarchies, progressions, etc.  
-  - This would be more of a graphical UI
-  - Cards can represent different things
-    - Another workspace / document (show a summary or title or key conclusion)
-    - An atomic entry (raw input)
-    - ...
-  - This feels pretty complicated to implement...
-
-- 
-
-  
-
----
-
-### Raw Entries
-
-I think I'd rather start with raw entries and allow them to be structured as logical arguments or questions and answers or whatever.  The base is the raw entry though.  This is the most natural and flexible.
-
-Structure
-- Raw entry has a title (required) and body (not required)
-
-Now how do we add structure on top of that for logical arguments, types (premise, assumption, conclusion, question or answer, etc.)
-
-
-