ctxora 6.2.2 → 6.4.0

package/src/harness_context/skills/ecc/foundation-models-on-device/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: foundation-models-on-device
+description: Apple FoundationModels framework for on-device LLM — text generation, guided generation with @Generable, tool calling, and snapshot streaming in iOS 26+. Use when adding on-device LLM features with Apple FoundationModels on iOS 26+.
+---
+
+# FoundationModels: On-Device LLM (iOS 26)
+
+Patterns for integrating Apple's on-device language model into apps using the FoundationModels framework. Covers text generation, structured output with `@Generable`, custom tool calling, and snapshot streaming — all running on-device for privacy and offline support.
+
+## When to Activate
+
+- Building AI-powered features using Apple Intelligence on-device
+- Generating or summarizing text without cloud dependency
+- Extracting structured data from natural language input
+- Implementing custom tool calling for domain-specific AI actions
+- Streaming structured responses for real-time UI updates
+- Need privacy-preserving AI (no data leaves the device)
+
+## Core Pattern — Availability Check
+
+Always check model availability before creating a session:
+
+```swift
+struct GenerativeView: View {
+    private var model = SystemLanguageModel.default
+
+    var body: some View {
+        switch model.availability {
+        case .available:
+            ContentView()
+        case .unavailable(.deviceNotEligible):
+            Text("Device not eligible for Apple Intelligence")
+        case .unavailable(.appleIntelligenceNotEnabled):
+            Text("Please enable Apple Intelligence in Settings")
+        case .unavailable(.modelNotReady):
+            Text("Model is downloading or not ready")
+        case .unavailable(let other):
+            Text("Model unavailable: \(other)")
+        }
+    }
+}
+```
+
+## Core Pattern — Basic Session
+
+```swift
+// Single-turn: create a new session each time
+let session = LanguageModelSession()
+let response = try await session.respond(to: "What's a good month to visit Paris?")
+print(response.content)
+
+// Multi-turn: reuse session for conversation context
+let session = LanguageModelSession(instructions: """
+    You are a cooking assistant.
+    Provide recipe suggestions based on ingredients.
+    Keep suggestions brief and practical.
+    """)
+
+let first = try await session.respond(to: "I have chicken and rice")
+let followUp = try await session.respond(to: "What about a vegetarian option?")
+```
+
+Key points for instructions:
+- Define the model's role ("You are a mentor")
+- Specify what to do ("Help extract calendar events")
+- Set style preferences ("Respond as briefly as possible")
+- Add safety measures ("Respond with 'I can't help with that' for dangerous requests")
+
+## Core Pattern — Guided Generation with @Generable
+
+Generate structured Swift types instead of raw strings:
+
+### 1. Define a Generable Type
+
+```swift
+@Generable(description: "Basic profile information about a cat")
+struct CatProfile {
+    var name: String
+
+    @Guide(description: "The age of the cat", .range(0...20))
+    var age: Int
+
+    @Guide(description: "A one sentence profile about the cat's personality")
+    var profile: String
+}
+```
+
+### 2. Request Structured Output
+
+```swift
+let response = try await session.respond(
+    to: "Generate a cute rescue cat",
+    generating: CatProfile.self
+)
+
+// Access structured fields directly
+print("Name: \(response.content.name)")
+print("Age: \(response.content.age)")
+print("Profile: \(response.content.profile)")
+```
+
+### Supported @Guide Constraints
+
+- `.range(0...20)` — numeric range
+- `.count(3)` — array element count
+- `description:` — semantic guidance for generation
+
+## Core Pattern — Tool Calling
+
+Let the model invoke custom code for domain-specific tasks:
+
+### 1. Define a Tool
+
+```swift
+struct RecipeSearchTool: Tool {
+    let name = "recipe_search"
+    let description = "Search for recipes matching a given term and return a list of results."
+
+    @Generable
+    struct Arguments {
+        var searchTerm: String
+        var numberOfResults: Int
+    }
+
+    func call(arguments: Arguments) async throws -> ToolOutput {
+        let recipes = await searchRecipes(
+            term: arguments.searchTerm,
+            limit: arguments.numberOfResults
+        )
+        return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
+    }
+}
+```
+
+### 2. Create Session with Tools
+
+```swift
+let session = LanguageModelSession(tools: [RecipeSearchTool()])
+let response = try await session.respond(to: "Find me some pasta recipes")
+```
+
+### 3. Handle Tool Errors
+
+```swift
+do {
+    let answer = try await session.respond(to: "Find a recipe for tomato soup.")
+} catch let error as LanguageModelSession.ToolCallError {
+    print(error.tool.name)
+    if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
+        // Handle specific tool error
+    }
+}
+```
+
+## Core Pattern — Snapshot Streaming
+
+Stream structured responses for real-time UI with `PartiallyGenerated` types:
+
+```swift
+@Generable
+struct TripIdeas {
+    @Guide(description: "Ideas for upcoming trips")
+    var ideas: [String]
+}
+
+let stream = session.streamResponse(
+    to: "What are some exciting trip ideas?",
+    generating: TripIdeas.self
+)
+
+for try await partial in stream {
+    // partial: TripIdeas.PartiallyGenerated (all properties Optional)
+    print(partial)
+}
+```
+
+### SwiftUI Integration
+
+```swift
+@State private var partialResult: TripIdeas.PartiallyGenerated?
+@State private var errorMessage: String?
+
+var body: some View {
+    List {
+        ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
+            Text(idea)
+        }
+    }
+    .overlay {
+        if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
+    }
+    .task {
+        do {
+            let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
+            for try await partial in stream {
+                partialResult = partial
+            }
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+}
+```
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| On-device execution | Privacy — no data leaves the device; works offline |
+| 4,096 token limit | On-device model constraint; chunk large data across sessions |
+| Snapshot streaming (not deltas) | Structured output friendly; each snapshot is a complete partial state |
+| `@Generable` macro | Compile-time safety for structured generation; auto-generates `PartiallyGenerated` type |
+| Single request per session | `isResponding` prevents concurrent requests; create multiple sessions if needed |
+| `response.content` (not `.output`) | Correct API — always access results via `.content` property |
+
+## Best Practices
+
+- **Always check `model.availability`** before creating a session — handle all unavailability cases
+- **Use `instructions`** to guide model behavior — they take priority over prompts
+- **Check `isResponding`** before sending a new request — sessions handle one request at a time
+- **Access `response.content`** for results — not `.output`
+- **Break large inputs into chunks** — 4,096 token limit applies to instructions + prompt + output combined
+- **Use `@Generable`** for structured output — stronger guarantees than parsing raw strings
+- **Use `GenerationOptions(temperature:)`** to tune creativity (higher = more creative)
+- **Monitor with Instruments** — use Xcode Instruments to profile request performance
+
+## Anti-Patterns to Avoid
+
+- Creating sessions without checking `model.availability` first
+- Sending inputs exceeding the 4,096 token context window
+- Attempting concurrent requests on a single session
+- Using `.output` instead of `.content` to access response data
+- Parsing raw string responses when `@Generable` structured output would work
+- Building complex multi-step logic in a single prompt — break into multiple focused prompts
+- Assuming the model is always available — device eligibility and settings vary
+
+## When to Use
+
+- On-device text generation for privacy-sensitive apps
+- Structured data extraction from user input (forms, natural language commands)
+- AI-assisted features that must work offline
+- Streaming UI that progressively shows generated content
+- Domain-specific AI actions via tool calling (search, compute, lookup)

package/src/harness_context/skills/ecc/frontend-a11y/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/frontend-a11y/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: frontend-a11y
+description: >
+  Accessibility patterns for React and Next.js — semantic HTML, ARIA attributes,
+  form labeling, keyboard navigation, focus management, and screen reader support.
+  Use when building any interactive UI component or form.
+metadata:
+  origin: community
+---
+
+# Frontend Accessibility Patterns
+
+Practical accessibility patterns for React and Next.js. Covers the issues most commonly flagged in code review: missing form labels, incorrect ARIA usage, non-semantic interactive elements, and broken keyboard navigation.
+
+## When to Activate
+
+- Building or reviewing form components (`<input>`, `<select>`, `<textarea>`)
+- Creating interactive elements (modals, dropdowns, tooltips, tabs)
+- Using `<div>` or `<span>` with `onClick`
+- Adding `aria-*` attributes to any element
+- Implementing keyboard navigation or focus management
+- Receiving accessibility feedback from code review tools (CodeRabbit, ESLint a11y)
+- Building components that must support screen readers
+
+## Form Accessibility
+
+Missing `htmlFor` / `id` pairing and disconnected error messages are the most common issues flagged in code review.
+
+### Label Connection
+
+```tsx
+// BAD: label has no connection to input — screen readers cannot associate them
+<label>Email</label>
+<input type="email" />
+
+// GOOD: htmlFor matches input id
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+```
+
+### Required Fields
+
+```tsx
+// BAD: visual-only asterisk conveys nothing to screen readers
+<label htmlFor="email">Email *</label>
+<input id="email" type="email" />
+
+// GOOD: required enables native browser validation; aria-required signals it to screen readers
+<label htmlFor="email">
+  Email <span aria-hidden="true">*</span>
+</label>
+<input id="email" type="email" required aria-required="true" />
+```
+
+### Error Messages
+
+```tsx
+// BAD: error text exists visually but is not linked to the input
+<input id="email" type="email" />
+<span className="error">Invalid email address</span>
+
+// GOOD: aria-describedby connects input to its error message
+// aria-invalid signals the invalid state to screen readers
+<input
+  id="email"
+  type="email"
+  aria-describedby="email-error"
+  aria-invalid={!!error}
+/>
+{error && (
+  <span id="email-error" role="alert">
+    {error}
+  </span>
+)}
+```
+
+### Complete Accessible Form
+
+```tsx
+interface LoginFormProps {
+  onSubmit: (email: string, password: string) => void;
+}
+
+export function LoginForm({ onSubmit }: LoginFormProps) {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [errors, setErrors] = useState<{ email?: string; password?: string }>({});
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const newErrors: typeof errors = {};
+    if (!email) newErrors.email = 'Email is required';
+    if (!password) newErrors.password = 'Password is required';
+    if (Object.keys(newErrors).length) {
+      setErrors(newErrors);
+      return;
+    }
+    onSubmit(email, password);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} noValidate>
+      <div>
+        <label htmlFor="email">
+          Email <span aria-hidden="true">*</span>
+        </label>
+        <input
+          id="email"
+          type="email"
+          value={email}
+          onChange={e => setEmail(e.target.value)}
+          aria-required="true"
+          aria-describedby={errors.email ? 'email-error' : undefined}
+          aria-invalid={!!errors.email}
+          autoComplete="email"
+        />
+        {errors.email && (
+          <span id="email-error" role="alert">
+            {errors.email}
+          </span>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="password">
+          Password <span aria-hidden="true">*</span>
+        </label>
+        <input
+          id="password"
+          type="password"
+          value={password}
+          onChange={e => setPassword(e.target.value)}
+          aria-required="true"
+          aria-describedby={errors.password ? 'password-error' : undefined}
+          aria-invalid={!!errors.password}
+          autoComplete="current-password"
+        />
+        {errors.password && (
+          <span id="password-error" role="alert">
+            {errors.password}
+          </span>
+        )}
+      </div>
+
+      <button type="submit">Log in</button>
+    </form>
+  );
+}
+```
+
+## Semantic HTML
+
+Use the element that matches the intent. Screen readers and keyboard users depend on native semantics.
+
+```tsx
+// BAD: div has no role, no keyboard support, no accessible name
+<div onClick={handleClick}>Submit</div>
+
+// GOOD: button is focusable, activates on Enter/Space, announces as "button"
+<button type="button" onClick={handleClick}>Submit</button>
+```
+
+```tsx
+// BAD: non-semantic navigation
+<div onClick={() => navigate('/home')}>Home</div>
+
+// GOOD: anchor supports right-click, middle-click, and keyboard navigation
+<a href="/home">Home</a>
+```
+
+```tsx
+// BAD: heading hierarchy skipped (h1 to h4)
+<h1>Dashboard</h1>
+<h4>Recent Activity</h4>
+
+// GOOD: sequential heading levels
+<h1>Dashboard</h1>
+<h2>Recent Activity</h2>
+```
+
+## ARIA Attributes
+
+Use ARIA only when native HTML semantics are insufficient. Wrong ARIA is worse than no ARIA.
+
+### aria-label vs aria-labelledby
+
+```tsx
+// aria-label: inline string label — use when no visible label text exists
+<button aria-label="Close modal">
+  <XIcon />
+</button>
+
+// aria-labelledby: references another element's text — use when a visible label exists
+<section aria-labelledby="section-title">
+  <h2 id="section-title">Recent Orders</h2>
+  {/* content */}
+</section>
+```
+
+### aria-describedby
+
+```tsx
+// Provides supplementary description beyond the label
+<button
+  aria-describedby="delete-warning"
+  onClick={handleDelete}
+> Delete account
+</button>
+<p id="delete-warning">This action cannot be undone.</p>
+```
+
+### aria-live for Dynamic Content
+
+```tsx
+// Use aria-live to announce content that updates without a page reload
+// polite: waits for user to finish current action before announcing
+// assertive: interrupts immediately — use only for urgent errors
+
+export function StatusMessage({ message, isError }: { message: string; isError?: boolean }) {
+  return (
+    <div role="status" aria-live={isError ? 'assertive' : 'polite'} aria-atomic="true">
+      {message}
+    </div>
+  );
+}
+```
+
+### aria-expanded and aria-controls
+
+```tsx
+export function Accordion({ title, children }: { title: string; children: React.ReactNode }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const contentId = useId();
+
+  return (
+    <div>
+      <button aria-expanded={isOpen} aria-controls={contentId} onClick={() => setIsOpen(prev => !prev)}>
+        {title}
+      </button>
+      <div id={contentId} hidden={!isOpen}>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+## Keyboard Navigation
+
+Every interactive element must be reachable and operable by keyboard alone.
+
+### Custom Dropdown
+
+```tsx
+export function Dropdown({ options, onSelect }: { options: string[]; onSelect: (value: string) => void }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const listId = useId();
+
+  if (!options.length) return null;
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        setActiveIndex(i => Math.min(i + 1, options.length - 1));
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        setActiveIndex(i => Math.max(i - 1, 0));
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        if (isOpen) onSelect(options[activeIndex]);
+        setIsOpen(prev => !prev);
+        break;
+      case 'Escape':
+        setIsOpen(false);
+        break;
+    }
+  };
+
+  return (
+    <div
+      role="combobox"
+      aria-expanded={isOpen}
+      aria-haspopup="listbox"
+      aria-controls={listId}
+      tabIndex={0}
+      onKeyDown={handleKeyDown}
+      onClick={() => setIsOpen(prev => !prev)}
+    >
+      <span>{options[activeIndex]}</span>
+      {isOpen && (
+        <ul id={listId} role="listbox">
+          {options.map((option, index) => (
+            <li
+              key={option}
+              role="option"
+              aria-selected={index === activeIndex}
+              onClick={() => {
+                onSelect(option);
+                setIsOpen(false);
+              }}
+            >
+              {option}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+## Focus Management
+
+Focus must move logically when UI state changes — especially for modals and route transitions.
+
+### Modal Focus Restoration
+
+> This example covers initial focus and restoration. For a full focus trap (Tab/Shift+Tab cycling within the modal), use a library like [`focus-trap-react`](https://github.com/focus-trap/focus-trap-react) which handles edge cases like dynamic content and nested portals.
+
+```tsx
+export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; onClose: () => void; title: string; children: React.ReactNode }) {
+  const modalRef = useRef<HTMLDivElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Save currently focused element and move focus into modal
+      previousFocusRef.current = document.activeElement as HTMLElement;
+      modalRef.current?.focus();
+    } else {
+      // Restore focus to the element that opened the modal
+      previousFocusRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div ref={modalRef} role="dialog" aria-modal="true" aria-labelledby="modal-title" tabIndex={-1} onKeyDown={e => e.key === 'Escape' && onClose()}>
+      <h2 id="modal-title">{title}</h2>
+      {children}
+      <button onClick={onClose}>Close</button>
+    </div>
+  );
+}
+```
+
+## Images and Icons
+
+```tsx
+// BAD: decorative icon announced as unlabeled image
+<img src="/icon.svg" />
+
+// GOOD: decorative image hidden from screen readers
+<img src="/decoration.png" alt="" aria-hidden="true" />
+
+// GOOD: meaningful image with descriptive alt text
+<img src="/chart.png" alt="Monthly revenue increased 23% from January to March" />
+
+// GOOD: icon button with accessible label
+<button aria-label="Delete item">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+## Reduced Motion
+
+Respect users who have requested reduced motion in their OS settings.
+
+```tsx
+export function useReducedMotion(): boolean {
+  const [prefersReduced, setPrefersReduced] = useState(false);
+
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    setPrefersReduced(mq.matches);
+    const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  return prefersReduced;
+}
+
+// Usage
+export function AnimatedCard({ children }: { children: React.ReactNode }) {
+  const reduceMotion = useReducedMotion();
+
+  return (
+    <div
+      style={{
+        transition: reduceMotion ? 'none' : 'transform 300ms ease'
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+## Anti-Patterns
+
+```tsx
+// BAD: onClick on non-interactive element with no keyboard support
+<div onClick={handleClick}>Click me</div>
+
+// BAD: aria-label on a div that has no role
+<div aria-label="Navigation">...</div>
+
+// BAD: placeholder used as a substitute for label
+<input placeholder="Enter your email" />
+
+// BAD: positive tabIndex creates unpredictable tab order
+<button tabIndex={3}>Submit</button>
+
+// BAD: aria-hidden on a focusable element — keyboard users get trapped
+<button aria-hidden="true">Open</button>
+
+// BAD: role="button" on div without keyboard handler
+<div role="button" onClick={handleClick}>Submit</div>
+// Missing: tabIndex={0}, onKeyDown for Enter/Space
+```
+
+## Checklist
+
+Before submitting any interactive component for review:
+
+- [ ] Every `<input>`, `<select>`, and `<textarea>` has a connected `<label>` via `htmlFor`/`id`
+- [ ] Error messages are linked with `aria-describedby` and marked `role="alert"`
+- [ ] No `onClick` on `<div>` or `<span>` without `role`, `tabIndex`, and `onKeyDown`
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Decorative images use `alt=""` and `aria-hidden="true"`
+- [ ] Modals restore focus on close (for full focus trapping with Tab/Shift+Tab cycling, use a library like `focus-trap-react`)
+- [ ] Dynamic content updates use `aria-live`
+- [ ] `prefers-reduced-motion` is respected for animations
+
+## Related Skills
+
+- `frontend-patterns` — general React component and state patterns
+- `design-system` — design token and component consistency
+- `motion-ui` — animation patterns with accessibility considerations