clawport-ui 0.1.0

package/components/docs/ThemingSection.tsx

@@ -0,0 +1,257 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  Table,
+  BulletList,
+  NumberedList,
+  Callout,
+  InfoCard,
+} from "./DocSection";
+
+export function ThemingSection() {
+  return (
+    <>
+      <Heading>Theming</Heading>
+      <Paragraph>
+        ClawPort's visual theming is driven entirely by CSS custom properties
+        and two React context providers: ThemeProvider and SettingsProvider.
+        Five built-in themes are toggled via the sidebar theme picker.
+      </Paragraph>
+
+      <SubHeading>Available Themes</SubHeading>
+      <Table
+        headers={["ID", "Label", "Description"]}
+        rows={[
+          [
+            <InlineCode key="d">dark</InlineCode>,
+            "Dark",
+            "Apple Dark Mode. The default theme.",
+          ],
+          [
+            <InlineCode key="g">glass</InlineCode>,
+            "Glass",
+            "Frosted glass dark variant with translucent surfaces.",
+          ],
+          [
+            <InlineCode key="c">color</InlineCode>,
+            "Color",
+            "Vibrant purple-indigo variant.",
+          ],
+          [
+            <InlineCode key="l">light</InlineCode>,
+            "Light",
+            "Apple Light Mode.",
+          ],
+          [
+            <InlineCode key="s">system</InlineCode>,
+            "System",
+            "Follows the OS prefers-color-scheme setting.",
+          ],
+        ]}
+      />
+
+      <SubHeading>Three-Layer System</SubHeading>
+      <NumberedList
+        items={[
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              data-theme attribute on &lt;html&gt;
+            </strong>{" "}
+            -- Each theme defines a CSS rule block scoped to{" "}
+            <InlineCode>[data-theme="id"]</InlineCode>. The dark theme also
+            matches <InlineCode>:root</InlineCode>.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              CSS custom properties
+            </strong>{" "}
+            -- Every color, shadow, radius, and material is expressed as a CSS
+            variable. Components consume these via inline styles. No Tailwind
+            color classes are used directly.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              ThemeProvider
+            </strong>{" "}
+            (<InlineCode>app/providers.tsx</InlineCode>) -- React context that
+            manages theme state, reads/writes localStorage, and sets the
+            data-theme attribute on &lt;html&gt;.
+          </>,
+        ]}
+      />
+
+      <SubHeading>CSS Custom Properties</SubHeading>
+
+      <InfoCard title="Backgrounds">
+        <Table
+          headers={["Token", "Purpose", "Dark Example"]}
+          rows={[
+            [<InlineCode key="b">--bg</InlineCode>, "Primary page background", "#000000"],
+            [
+              <InlineCode key="bs">--bg-secondary</InlineCode>,
+              "Card / surface background",
+              "rgba(28,28,30,1)",
+            ],
+            [
+              <InlineCode key="bt">--bg-tertiary</InlineCode>,
+              "Nested surface",
+              "rgba(44,44,46,1)",
+            ],
+          ]}
+        />
+      </InfoCard>
+
+      <InfoCard title="Materials (Apple translucent surfaces)">
+        <Table
+          headers={["Token", "Purpose"]}
+          rows={[
+            [
+              <InlineCode key="mr">--material-regular</InlineCode>,
+              "Standard material (sidebar, overlays)",
+            ],
+            [
+              <InlineCode key="mt">--material-thick</InlineCode>,
+              "Dense material",
+            ],
+            [
+              <InlineCode key="mn">--material-thin</InlineCode>,
+              "Light tint material",
+            ],
+            [
+              <InlineCode key="mu">--material-ultra-thin</InlineCode>,
+              "Very subtle tint",
+            ],
+          ]}
+        />
+      </InfoCard>
+
+      <InfoCard title="Text & Fills">
+        <Table
+          headers={["Token", "Purpose"]}
+          rows={[
+            [
+              <InlineCode key="tp">--text-primary</InlineCode>,
+              "Headings, body text",
+            ],
+            [
+              <InlineCode key="ts">--text-secondary</InlineCode>,
+              "Labels, supporting text",
+            ],
+            [
+              <InlineCode key="tt">--text-tertiary</InlineCode>,
+              "Placeholder, captions",
+            ],
+            [
+              <InlineCode key="fp">--fill-primary</InlineCode>,
+              "Primary interactive fill (buttons)",
+            ],
+            [
+              <InlineCode key="fs">--fill-secondary</InlineCode>,
+              "Hover fill",
+            ],
+            [
+              <InlineCode key="ft">--fill-tertiary</InlineCode>,
+              "Subtle fill (input backgrounds)",
+            ],
+          ]}
+        />
+      </InfoCard>
+
+      <InfoCard title="Accent & System Colors">
+        <Table
+          headers={["Token", "Purpose"]}
+          rows={[
+            [
+              <InlineCode key="a">--accent</InlineCode>,
+              "Primary brand accent (buttons, active states)",
+            ],
+            [
+              <InlineCode key="af">--accent-fill</InlineCode>,
+              "Accent at 15% opacity (backgrounds)",
+            ],
+            [<InlineCode key="sb">--system-blue</InlineCode>, "Links, focus rings"],
+            [<InlineCode key="sg">--system-green</InlineCode>, "Success, active toggles"],
+            [<InlineCode key="sr">--system-red</InlineCode>, "Errors, destructive actions"],
+            [<InlineCode key="so">--system-orange</InlineCode>, "Warnings"],
+            [<InlineCode key="sp">--system-purple</InlineCode>, "Tags, highlights"],
+          ]}
+        />
+      </InfoCard>
+
+      <InfoCard title="Code Blocks">
+        <Table
+          headers={["Token", "Purpose"]}
+          rows={[
+            [<InlineCode key="cb">--code-bg</InlineCode>, "Code block background"],
+            [<InlineCode key="cbd">--code-border</InlineCode>, "Code block border"],
+            [<InlineCode key="ct">--code-text</InlineCode>, "Code text color"],
+          ]}
+        />
+      </InfoCard>
+
+      <SubHeading>Accent Color Override</SubHeading>
+      <Paragraph>
+        When the user selects a custom accent color in settings, the
+        SettingsProvider applies it as inline styles on{" "}
+        <InlineCode>document.documentElement</InlineCode>, overriding the
+        theme's <InlineCode>--accent</InlineCode> and{" "}
+        <InlineCode>--accent-fill</InlineCode>. Setting it to null reverts to
+        the theme default.
+      </Paragraph>
+
+      <SubHeading>Adding a New Theme</SubHeading>
+      <NumberedList
+        items={[
+          <>
+            Add the theme ID to the <InlineCode>ThemeId</InlineCode> type
+            union and <InlineCode>THEMES</InlineCode> array in{" "}
+            <InlineCode>lib/themes.ts</InlineCode>.
+          </>,
+          <>
+            Add a <InlineCode>[data-theme="name"]</InlineCode> block in{" "}
+            <InlineCode>app/globals.css</InlineCode> defining every CSS custom
+            property token. Copy the dark theme block as a starting point.
+          </>,
+          "Optionally add theme-specific overrides (body background gradients, component styles).",
+          "The ThemeProvider, onboarding wizard, and settings page will automatically pick up the new theme.",
+        ]}
+      />
+
+      <Callout type="tip">
+        Missing tokens will cause components to render with broken styles.
+        Always define every token when creating a new theme -- use the dark theme
+        block as a complete template.
+      </Callout>
+
+      <SubHeading>Spacing & Typography</SubHeading>
+      <BulletList
+        items={[
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>Spacing</strong>{" "}
+            -- 4px grid: <InlineCode>--space-1</InlineCode> (4px) through{" "}
+            <InlineCode>--space-16</InlineCode> (64px)
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>Typography</strong>{" "}
+            -- Apple HIG scale: <InlineCode>--text-caption2</InlineCode> (11px)
+            through <InlineCode>--text-large-title</InlineCode> (34px)
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>Radius</strong>{" "}
+            -- <InlineCode>--radius-sm</InlineCode> (6px) through{" "}
+            <InlineCode>--radius-2xl</InlineCode> (24px)
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>Easing</strong>{" "}
+            -- <InlineCode>--ease-spring</InlineCode> (bouncy),{" "}
+            <InlineCode>--ease-smooth</InlineCode> (general),{" "}
+            <InlineCode>--ease-snappy</InlineCode> (quick)
+          </>,
+        ]}
+      />
+    </>
+  );
+}

package/components/docs/TroubleshootingSection.tsx

@@ -0,0 +1,200 @@
+import {
+  Heading,
+  SubHeading,
+  Paragraph,
+  CodeBlock,
+  InlineCode,
+  BulletList,
+  NumberedList,
+  Callout,
+} from "./DocSection";
+
+export function TroubleshootingSection() {
+  return (
+    <>
+      <Heading>Troubleshooting</Heading>
+      <Paragraph>
+        Common issues and their solutions when running ClawPort.
+      </Paragraph>
+
+      {/* ── Issue 1 ────────────────────────────────────────────── */}
+      <SubHeading>
+        "Missing required environment variable: WORKSPACE_PATH"
+      </SubHeading>
+      <Paragraph>
+        Your <InlineCode>.env.local</InlineCode> is missing or the variable
+        isn't set. Make sure you copied <InlineCode>.env.example</InlineCode>:
+      </Paragraph>
+      <CodeBlock>{`cp .env.example .env.local`}</CodeBlock>
+      <Paragraph>
+        Then fill in the values. Restart the dev server after changing{" "}
+        <InlineCode>.env.local</InlineCode>.
+      </Paragraph>
+
+      {/* ── Issue 2 ────────────────────────────────────────────── */}
+      <SubHeading>Gateway connection refused / chat not working</SubHeading>
+      <Paragraph>
+        The OpenClaw gateway isn't running. Start it:
+      </Paragraph>
+      <CodeBlock>{`openclaw gateway run`}</CodeBlock>
+      <Paragraph>Verify it's reachable:</Paragraph>
+      <CodeBlock>{`curl http://localhost:18789/v1/models`}</CodeBlock>
+      <Paragraph>
+        You should get a JSON response. If not, check that nothing else is using
+        port 18789.
+      </Paragraph>
+
+      {/* ── Issue 3 ────────────────────────────────────────────── */}
+      <SubHeading>No agents showing up</SubHeading>
+      <NumberedList
+        items={[
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Check WORKSPACE_PATH
+            </strong>{" "}
+            -- make sure it points to a valid OpenClaw workspace directory.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Check your agents.json
+            </strong>{" "}
+            -- if you placed a custom{" "}
+            <InlineCode>agents.json</InlineCode> at{" "}
+            <InlineCode>$WORKSPACE_PATH/clawport/agents.json</InlineCode>, make
+            sure it's valid JSON. A syntax error will cause a silent fallback to
+            the bundled registry.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Check the server console
+            </strong>{" "}
+            -- ClawPort logs errors to the terminal where{" "}
+            <InlineCode>npm run dev</InlineCode> is running.
+          </>,
+        ]}
+      />
+      <Callout type="tip">
+        Test your agents.json with:{" "}
+        <InlineCode>
+          cat $WORKSPACE_PATH/clawport/agents.json | python3 -m json.tool
+        </InlineCode>
+      </Callout>
+
+      {/* ── Issue 4 ────────────────────────────────────────────── */}
+      <SubHeading>Agent SOUL.md not loading</SubHeading>
+      <Paragraph>
+        The <InlineCode>soulPath</InlineCode> in your agents.json is relative to{" "}
+        <InlineCode>WORKSPACE_PATH</InlineCode>. If your workspace is at{" "}
+        <InlineCode>/Users/you/.openclaw/workspace</InlineCode> and soulPath is{" "}
+        <InlineCode>"agents/vera/SOUL.md"</InlineCode>, ClawPort will look for{" "}
+        <InlineCode>
+          /Users/you/.openclaw/workspace/agents/vera/SOUL.md
+        </InlineCode>
+        .
+      </Paragraph>
+      <Paragraph>Make sure the file exists at that path.</Paragraph>
+
+      {/* ── Issue 5 ────────────────────────────────────────────── */}
+      <SubHeading>Images not working in chat</SubHeading>
+      <Paragraph>
+        Image messages use the CLI pipeline. Common issues:
+      </Paragraph>
+      <NumberedList
+        items={[
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              OPENCLAW_BIN path is wrong
+            </strong>{" "}
+            -- run <InlineCode>which openclaw</InlineCode> and update{" "}
+            <InlineCode>.env.local</InlineCode>.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Gateway token is wrong
+            </strong>{" "}
+            -- verify with{" "}
+            <InlineCode>openclaw gateway status</InlineCode>.
+          </>,
+          <>
+            <strong style={{ color: "var(--text-primary)" }}>
+              Image too large
+            </strong>{" "}
+            -- ClawPort resizes to 1200px max, but extremely large images may
+            still hit limits. Try a smaller image.
+          </>,
+        ]}
+      />
+      <Paragraph>
+        Check the server console for errors like{" "}
+        <InlineCode>sendViaOpenClaw execFile error:</InlineCode> or{" "}
+        <InlineCode>E2BIG</InlineCode>.
+      </Paragraph>
+
+      {/* ── Issue 6 ────────────────────────────────────────────── */}
+      <SubHeading>Voice/TTS features not working</SubHeading>
+      <Paragraph>
+        Voice features require <InlineCode>ELEVENLABS_API_KEY</InlineCode> in
+        your <InlineCode>.env.local</InlineCode>. Without it, voice indicators
+        won't appear on agent profiles.
+      </Paragraph>
+      <Paragraph>
+        Audio transcription (speech-to-text) uses Whisper through the OpenClaw
+        gateway and does not require a separate key.
+      </Paragraph>
+
+      {/* ── Issue 7 ────────────────────────────────────────────── */}
+      <SubHeading>Port 3000 already in use</SubHeading>
+      <Paragraph>
+        Another process is using port 3000. Either stop it or run on a different
+        port:
+      </Paragraph>
+      <CodeBlock>{`npm run dev -- -p 3001`}</CodeBlock>
+
+      {/* ── Debug Image Pipeline ──────────────────────────────── */}
+      <SubHeading>Debug Image Pipeline</SubHeading>
+      <Paragraph>
+        Step-by-step debugging for the vision (image) chat pipeline:
+      </Paragraph>
+      <NumberedList
+        items={[
+          <>
+            Check server console for{" "}
+            <InlineCode>sendViaOpenClaw execFile error:</InlineCode> or{" "}
+            <InlineCode>sendViaOpenClaw: timed out</InlineCode>
+          </>,
+          <>
+            Test CLI directly:
+          </>,
+        ]}
+      />
+      <CodeBlock title="terminal">
+        {`# Test chat.send
+openclaw gateway call chat.send \\
+  --params '{"sessionKey":"agent:main:clawport","idempotencyKey":"test","message":"describe","attachments":[]}' \\
+  --token <token> --json
+
+# Check history
+openclaw gateway call chat.history \\
+  --params '{"sessionKey":"agent:main:clawport"}' \\
+  --token <token> --json
+
+# Verify gateway health
+openclaw gateway call health --token <token>`}
+      </CodeBlock>
+
+      <SubHeading>Running Tests</SubHeading>
+      <CodeBlock title="terminal">
+        {`npm test             # Run all 288 tests via Vitest
+npx tsc --noEmit     # Type-check (expect 0 errors)`}
+      </CodeBlock>
+
+      <Callout type="note">
+        All tests are in the <InlineCode>lib/</InlineCode> directory, colocated
+        with source files. Key test patterns include{" "}
+        <InlineCode>vi.mock('child_process')</InlineCode> for CLI tests,{" "}
+        <InlineCode>vi.useFakeTimers</InlineCode> for polling tests, and{" "}
+        <InlineCode>vi.stubEnv()</InlineCode> for environment variable tests.
+      </Callout>
+    </>
+  );
+}