@desktalk/core 0.1.0-alpha.1

package/dist/services/ai/manual-pages/desktop-actions.md

@@ -0,0 +1,36 @@
+# Desktop Actions
+
+Use the `action` tool to call MiniApp actions by name.
+
+## Source of Truth
+
+Every user message starts with a `[Desktop Context]` block.
+
+That block tells you:
+
+- `Home` — the absolute filesystem path to the user's home directory
+- which window is focused
+- which actions are registered on the focused window
+- the parameter schema for each action
+
+Read it before invoking `action`.
+
+## Rules
+
+- Provide all required params as a JSON object.
+- If `windowId` is omitted, the action runs on the focused window.
+- If you need to target a different window, pass `windowId` explicitly or focus that window first.
+
+## Preview Editing Pattern
+
+For Preview edits, use `Get State` first.
+
+The expected sequence is:
+
+1. Call the focused Preview action `Get State`.
+2. Read `file.path` from the action result — this is **relative to Home**.
+3. Join `file.path` with the `Home` path from `[Desktop Context]` to form an absolute path.
+4. Use the built-in `read` tool to inspect the file at the absolute path.
+5. Use `edit` with an exact `oldText` match.
+
+Do not guess Preview file paths.

package/dist/services/ai/manual-pages/desktop-windows.md

@@ -0,0 +1,24 @@
+# Desktop Windows
+
+Use the `desktop` tool for window-level operations.
+
+## Actions
+
+- `action="list"` -> get all open windows, the focused window, and available MiniApps
+- `action="open"` with `miniAppId` -> open a MiniApp window
+- `action="focus"` with `windowId` -> focus a window
+- `action="maximize"` with `windowId` -> maximize a window
+- `action="close"` with `windowId` -> close a window
+
+## Usage Patterns
+
+- Use `list` when you need fresh window IDs mid-conversation.
+- Use `open` when the user wants a MiniApp launched and you do not already have a suitable window.
+- If you need to act on a specific existing window, either focus it first or pass `windowId` explicitly.
+- Opening a MiniApp with the same shallow-equal args may focus the existing window instead of creating a duplicate.
+
+## Result Expectations
+
+- `list` returns the current window set plus focused-window actions.
+- `open` returns a `windowId` for the opened or focused window.
+- Mutating actions fail if the target window does not exist.

package/dist/services/ai/manual-pages/dt-badge.md

@@ -0,0 +1,36 @@
+# `<dt-badge>`
+
+Inline status pill/badge.
+
+## Attributes
+
+- `variant` — status color: `accent` (default), `success`, `danger`, `warning`, `info`, `neutral`
+- `size` — size: `sm`, `md` (default), `lg`
+- `text` — badge text (alternative to slot content)
+
+**When to use:** Use for status indicators, labels, category tags.
+
+## Examples
+
+```html
+<dt-badge>New</dt-badge>
+
+<dt-badge variant="success">Active</dt-badge>
+
+<dt-badge variant="danger" size="lg">Error</dt-badge>
+
+<dt-badge variant="info" size="sm">Beta</dt-badge>
+```
+
+## Full-Page Example — Status Badges
+
+```html
+<dt-stack direction="row" gap="8">
+  <dt-badge>Default</dt-badge>
+  <dt-badge variant="success">Success</dt-badge>
+  <dt-badge variant="warning">Warning</dt-badge>
+  <dt-badge variant="danger">Error</dt-badge>
+  <dt-badge variant="info">Info</dt-badge>
+  <dt-badge variant="neutral">Neutral</dt-badge>
+</dt-stack>
+```

package/dist/services/ai/manual-pages/dt-button.md

@@ -0,0 +1,38 @@
+# `<dt-button>`
+
+Themed button component.
+
+## Attributes
+
+- `variant` — button style: `primary` (default), `secondary`, `ghost`, `danger`
+- `size` — button size: `sm`, `md` (default), `lg`
+- `disabled` — disables the button
+- `fullwidth` — makes the button fill its container width
+- `type` — HTML button type: `button` (default), `submit`, `reset`
+
+**When to use:** Use for all clickable actions. Always prefer `<dt-button>` over `<button>` or `.btn` class.
+
+## Examples
+
+```html
+<dt-button>Save</dt-button>
+
+<dt-button variant="secondary">Cancel</dt-button>
+
+<dt-button variant="danger" size="sm">Delete</dt-button>
+
+<dt-button variant="ghost" disabled>Disabled</dt-button>
+
+<dt-button fullwidth>Full Width Button</dt-button>
+```
+
+## Full-Page Example — Action Buttons
+
+```html
+<dt-stack direction="row" gap="12" align="center">
+  <dt-button>Primary</dt-button>
+  <dt-button variant="secondary">Secondary</dt-button>
+  <dt-button variant="ghost">Ghost</dt-button>
+  <dt-button variant="danger">Danger</dt-button>
+</dt-stack>
+```

package/dist/services/ai/manual-pages/dt-card.md

@@ -0,0 +1,22 @@
+# `<dt-card>`
+
+Use `<dt-card>` for any visually grouped content: information panels, stat blocks, feature tiles, settings groups, and list items that need a visible container.
+
+## Attributes
+
+- `variant="default"` — solid surface background (default)
+- `variant="outlined"` — transparent background with border
+- `variant="filled"` — accent-subtle background
+
+## Examples
+
+```html
+<dt-card>
+  <h3>Title</h3>
+  <p>Card content goes here.</p>
+</dt-card>
+
+<dt-card variant="outlined">
+  <p>Outlined card with transparent background.</p>
+</dt-card>
+```

package/dist/services/ai/manual-pages/dt-chart.md

@@ -0,0 +1,261 @@
+# `<dt-chart>`
+
+Interactive chart component powered by Chart.js. Data is provided exclusively via the `.data` JS property.
+
+## Attributes
+
+- `type` — `bar` (default), `line`, `area`, `pie`, `doughnut`, `radar`, `scatter`, `bubble`
+- `labels` — comma-separated category labels such as `labels="Jan,Feb,Mar"` (convenience; can also set labels inside `.data`)
+- `legend` — `top`, `bottom`, `left`, `right`, `none` (default)
+- `stacked` — stacks bar and line datasets
+- `dt-chart-click` event — emitted with `{ label, datasetIndex, index, value }`
+
+## `.data` Property (required)
+
+All chart data **must** be set through the `.data` JS property. There is no HTML-only way to fill data.
+
+```ts
+interface DtChartData {
+  labels?: string[]; // category labels for the x-axis
+  datasets: DtChartDataset[];
+}
+
+interface DtChartDataset {
+  label?: string; // legend label for this series
+  data:
+    | number[] // values for bar, line, area, pie, doughnut, radar
+    | { x: number; y: number }[] // for scatter
+    | { x: number; y: number; r: number }[]; // for bubble
+  color?: string; // optional CSS color override; auto-assigned from theme palette if omitted
+}
+```
+
+## `.options` Property (advanced, rarely needed)
+
+Raw Chart.js options object merged under the auto-themed defaults. Only use this when you need fine-grained control over axes, tooltips, etc.
+
+## How to Use
+
+1. Create a `<dt-chart>` element in HTML with the desired `type`, `labels`, `legend`, and an **explicit height**.
+2. In a `<script>` block, select the element and assign its `.data` property.
+
+**Important:** The `<dt-chart>` element **requires an explicit height** via inline `style` or a CSS class. Without it the chart will not be visible.
+
+**When to use:** Use for charts, graphs, trends, comparisons, and composition breakdowns. Prefer `<dt-stat>` for single KPIs.
+
+## Examples
+
+### Bar chart with two datasets
+
+```html
+<dt-chart
+  id="revenue"
+  type="bar"
+  legend="top"
+  labels="Jan,Feb,Mar,Apr"
+  style="height: 300px"
+></dt-chart>
+
+<script>
+  document.getElementById('revenue').data = {
+    datasets: [
+      { label: 'Revenue', data: [12, 19, 3, 5] },
+      { label: 'Costs', data: [7, 11, 5, 8] },
+    ],
+  };
+</script>
+```
+
+### Doughnut chart
+
+```html
+<dt-chart
+  id="categories"
+  type="doughnut"
+  legend="right"
+  labels="Electronics,Clothing,Food"
+  style="height: 250px"
+></dt-chart>
+
+<script>
+  document.getElementById('categories').data = {
+    datasets: [{ label: 'Sales', data: [35, 25, 22] }],
+  };
+</script>
+```
+
+### Line chart (area fill)
+
+```html
+<dt-chart
+  id="growth"
+  type="area"
+  legend="none"
+  labels="Jan,Feb,Mar,Apr,May,Jun"
+  style="height: 300px"
+></dt-chart>
+
+<script>
+  document.getElementById('growth').data = {
+    datasets: [{ label: 'Users', data: [150, 230, 224, 318, 435, 547] }],
+  };
+</script>
+```
+
+### Scatter chart
+
+```html
+<dt-chart id="scatter" type="scatter" legend="top" style="height: 300px"></dt-chart>
+
+<script>
+  document.getElementById('scatter').data = {
+    datasets: [
+      {
+        label: 'Samples',
+        data: [
+          { x: 1, y: 2 },
+          { x: 3, y: 4 },
+          { x: 5, y: 1 },
+        ],
+      },
+    ],
+  };
+</script>
+```
+
+### Radar chart
+
+```html
+<dt-chart
+  id="radar"
+  type="radar"
+  legend="bottom"
+  labels="Speed,Reliability,Comfort,Safety,Efficiency"
+  style="height: 250px"
+></dt-chart>
+
+<script>
+  document.getElementById('radar').data = {
+    datasets: [
+      { label: 'Model A', data: [65, 59, 90, 81, 56] },
+      { label: 'Model B', data: [28, 48, 40, 19, 96] },
+    ],
+  };
+</script>
+```
+
+### Stacked bar chart
+
+```html
+<dt-chart
+  id="stacked"
+  type="bar"
+  legend="top"
+  stacked
+  labels="Jan,Feb,Mar,Apr,May,Jun"
+  style="height: 300px"
+></dt-chart>
+
+<script>
+  document.getElementById('stacked').data = {
+    datasets: [
+      { label: 'Online', data: [12, 19, 3, 5, 2, 3] },
+      { label: 'Retail', data: [7, 11, 5, 8, 3, 7] },
+    ],
+  };
+</script>
+```
+
+## Full-Page Example — Sales Dashboard Charts
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sales Dashboard</title>
+    <style>
+      body {
+        background: var(--dt-bg);
+      }
+
+      .chart-box {
+        height: 300px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Sales Dashboard</h1>
+    <dt-grid cols="2" gap="16">
+      <dt-card>
+        <h2>Revenue by Month</h2>
+        <dt-chart
+          id="revenue-chart"
+          type="bar"
+          legend="top"
+          stacked
+          labels="Jan,Feb,Mar,Apr,May,Jun"
+          class="chart-box"
+        ></dt-chart>
+      </dt-card>
+
+      <dt-card>
+        <h2>User Growth</h2>
+        <dt-chart
+          id="growth-chart"
+          type="area"
+          legend="none"
+          labels="Jan,Feb,Mar,Apr,May,Jun"
+          class="chart-box"
+        ></dt-chart>
+      </dt-card>
+    </dt-grid>
+
+    <dt-card style="margin-top: 16px">
+      <h2>Category Breakdown</h2>
+      <dt-grid cols="2" gap="16">
+        <dt-chart
+          id="category-chart"
+          type="doughnut"
+          legend="right"
+          labels="Electronics,Clothing,Food,Books"
+          style="height: 250px"
+        ></dt-chart>
+
+        <dt-chart
+          id="comparison-chart"
+          type="radar"
+          legend="bottom"
+          labels="Speed,Reliability,Comfort,Safety,Efficiency"
+          style="height: 250px"
+        ></dt-chart>
+      </dt-grid>
+    </dt-card>
+
+    <script>
+      document.getElementById('revenue-chart').data = {
+        datasets: [
+          { label: 'Online', data: [12, 19, 3, 5, 2, 3] },
+          { label: 'Retail', data: [7, 11, 5, 8, 3, 7] },
+        ],
+      };
+
+      document.getElementById('growth-chart').data = {
+        datasets: [{ label: 'Users', data: [150, 230, 224, 318, 435, 547] }],
+      };
+
+      document.getElementById('category-chart').data = {
+        datasets: [{ label: 'Sales', data: [35, 25, 22, 18] }],
+      };
+
+      document.getElementById('comparison-chart').data = {
+        datasets: [
+          { label: 'Model A', data: [65, 59, 90, 81, 56] },
+          { label: 'Model B', data: [28, 48, 40, 19, 96] },
+        ],
+      };
+    </script>
+  </body>
+</html>
+```

package/dist/services/ai/manual-pages/dt-divider.md

@@ -0,0 +1,25 @@
+# `<dt-divider>`
+
+Horizontal or vertical separator line.
+
+## Attributes
+
+- `direction` — orientation: `horizontal` (default) or `vertical`
+- `style-variant` — border style: `default`, `subtle`, `strong`
+- `spacing` — margin around divider: `sm`, `md`, `lg`
+
+**When to use:** Use to separate sections or items in a list.
+
+## Examples
+
+```html
+<!-- Horizontal divider (default) -->
+<dt-divider></dt-divider>
+
+<!-- Vertical divider in a row layout -->
+<dt-stack direction="row">
+  <span>Left</span>
+  <dt-divider direction="vertical"></dt-divider>
+  <span>Right</span>
+</dt-stack>
+```

package/dist/services/ai/manual-pages/dt-grid.md

@@ -0,0 +1,29 @@
+# `<dt-grid>`
+
+Auto-responsive grid layout. Columns collapse automatically in narrow views.
+
+## Attributes
+
+- `cols` — fixed number of columns: `1`, `2`, `3`, `4`, `5`, `6` (auto-fit responsive when omitted)
+- `gap` — spacing between items: `0`, `4`, `8`, `12`, `16`, `20`, `24`, `32` (default: `16`)
+- `min-width` — minimum width for auto-fit columns: `150`, `180`, `200`, `220`, `260`, `300` (default: `220`)
+
+**When to use:** Use for any multi-column layout. Prefer omitting `cols` for auto-responsive behavior unless you need a specific number of columns.
+
+## Examples
+
+```html
+<!-- Auto-responsive: columns collapse based on available space -->
+<dt-grid>
+  <dt-card>Item 1</dt-card>
+  <dt-card>Item 2</dt-card>
+  <dt-card>Item 3</dt-card>
+</dt-grid>
+
+<!-- Fixed 3 columns, collapses to 1 on mobile -->
+<dt-grid cols="3" gap="24">
+  <dt-stat label="CPU" value="42%"></dt-stat>
+  <dt-stat label="RAM" value="8GB"></dt-stat>
+  <dt-stat label="Disk" value="256GB"></dt-stat>
+</dt-grid>
+```

package/dist/services/ai/manual-pages/dt-list-view.md

@@ -0,0 +1,96 @@
+# `<dt-list-view>`
+
+Virtualized list for long collections. Supports fixed-height rows when `item-height` is provided and variable-height measurement mode when omitted.
+
+## Attributes
+
+- `item-height` — fixed row height in px; omit for variable-height measurement mode
+- `dividers` — show dividers between rows
+- `selectable` — `none`, `single`, or `multi`
+- `empty-text` — empty-state text
+- `.items` JS property — array of list item objects
+- `dt-item-click` event — emitted when a row is clicked
+- `dt-selection-change` event — emitted when selection changes
+
+**When to use:** Use for task lists, logs, search results, files, and any long collection that might grow beyond a few dozen rows.
+
+## Examples
+
+```html
+<dt-list-view id="task-list" item-height="72" dividers selectable="single">
+  <template>
+    <dt-stack gap="8">
+      <dt-stack direction="row" align="center" gap="8">
+        <strong data-field="title"></strong>
+        <dt-badge data-field="status" data-field-variant="statusVariant"></dt-badge>
+      </dt-stack>
+      <span class="text-muted" data-field="summary"></span>
+    </dt-stack>
+  </template>
+</dt-list-view>
+
+<script>
+  document.getElementById('task-list').items = [
+    {
+      title: 'Review report',
+      status: 'Queued',
+      statusVariant: 'warning',
+      summary: 'Waiting on CPU budget',
+    },
+    {
+      title: 'Publish build',
+      status: 'Done',
+      statusVariant: 'success',
+      summary: 'Released 4 minutes ago',
+    },
+  ];
+</script>
+```
+
+## Full-Page Example — Virtualized Log List
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Deployment Logs</title>
+    <style>
+      body {
+        background: var(--dt-bg);
+      }
+
+      #log-list {
+        height: 360px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Deployment Logs</h1>
+    <dt-card>
+      <dt-list-view id="log-list" item-height="68" dividers>
+        <template>
+          <dt-stack gap="8">
+            <dt-stack direction="row" align="center" gap="8">
+              <strong data-field="service"></strong>
+              <dt-badge data-field="level" data-field-variant="variant"></dt-badge>
+            </dt-stack>
+            <span class="text-muted" data-field="message"></span>
+          </dt-stack>
+        </template>
+      </dt-list-view>
+    </dt-card>
+
+    <script>
+      const list = document.getElementById('log-list');
+      list.items = Array.from({ length: 250 }, (_, index) => ({
+        service: `agent-${(index % 8) + 1}`,
+        level: index % 5 === 0 ? 'warn' : 'info',
+        variant: index % 5 === 0 ? 'warning' : 'info',
+        message: `Processed batch ${index + 1} successfully.`,
+      }));
+    </script>
+  </body>
+</html>
+```

package/dist/services/ai/manual-pages/dt-markdown-editor.md

@@ -0,0 +1,90 @@
+# `<dt-markdown-editor>`
+
+WYSIWYG markdown editor powered by Milkdown. Users edit formatted content directly, while the component stores and returns markdown.
+
+## Attributes
+
+- `placeholder` — empty editor hint text
+- `readonly` — makes the editor read-only
+- `.value` JS property — get or replace the current markdown document
+- `dt-change` event — emitted with `{ value }` after content changes (debounced)
+- `dt-focus` event — emitted when the editor gains focus
+- `dt-blur` event — emitted when the editor loses focus
+
+**When to use:** Use for notes, documentation, comments, change logs, prompts, and any workflow that needs rich text authoring without building your own editor UI.
+
+## Examples
+
+```html
+<dt-markdown-editor
+  id="note-editor"
+  placeholder="Write something..."
+  style="height: 400px"
+></dt-markdown-editor>
+<dt-button id="save-note">Save</dt-button>
+
+<script>
+  const editor = document.getElementById('note-editor');
+  editor.value = '# Team Notes\n\n- Review onboarding docs\n- Schedule release check';
+
+  document.getElementById('save-note').addEventListener('click', () => {
+    window.DeskTalk.storage.set('notes.latest', editor.value);
+  });
+</script>
+```
+
+## Full-Page Example — Markdown Note Editor
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Notes</title>
+    <style>
+      body {
+        background: var(--dt-bg);
+      }
+
+      #editor {
+        height: 420px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Operations Notes</h1>
+    <dt-stack gap="12">
+      <dt-stack direction="row" align="center" gap="8">
+        <dt-button id="save">Save</dt-button>
+        <dt-badge id="status" variant="neutral">Saved</dt-badge>
+      </dt-stack>
+      <dt-card>
+        <dt-markdown-editor id="editor" placeholder="Capture findings..."></dt-markdown-editor>
+      </dt-card>
+    </dt-stack>
+
+    <script>
+      const editor = document.getElementById('editor');
+      const status = document.getElementById('status');
+      const save = document.getElementById('save');
+      const saved =
+        window.DeskTalk.storage.get('ops.note') ||
+        '# Incident Review\n\n## Timeline\n\n- 09:00 Started investigation';
+
+      editor.value = saved;
+
+      editor.addEventListener('dt-change', () => {
+        status.textContent = 'Unsaved';
+        status.setAttribute('variant', 'warning');
+      });
+
+      save.addEventListener('click', () => {
+        window.DeskTalk.storage.set('ops.note', editor.value);
+        status.textContent = 'Saved';
+        status.setAttribute('variant', 'success');
+      });
+    </script>
+  </body>
+</html>
+```