@crossworks/client-types 0.230.43

package/LICENSE.md

@@ -0,0 +1,135 @@
+# License
+
+Mantle is **dual-licensed** by Cross Works Engineering (Pty) Ltd:
+
+1. **Public license — Functional Source License 1.1 (MIT Future), reproduced in
+   full below.** Free to use, self-host, modify, and run for any purpose that is
+   not a Competing Use (see the _Permitted Purpose_ clause). Two years after each
+   version is first published, that version automatically converts to the MIT
+   license.
+2. **Commercial license — see [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md).**
+   A paid agreement that lifts the FSL's _Competing Use_ restriction for partners
+   who want to embed Mantle in a commercial product or offer it as a service
+   during the two-year window. Contact **licensing@crossworks.engineering**.
+
+For a plain-language explanation of how the two licenses fit together and what the
+key terms mean, see [`LICENSING.md`](./LICENSING.md). Third-party open-source
+components bundled with Mantle are attributed in
+[`THIRD-PARTY-NOTICES.md`](./THIRD-PARTY-NOTICES.md).
+
+The "Change Date" for each release is **two years after that release is first made
+available** under this license; on the Change Date that release becomes available
+under the MIT license (the _Grant of Future License_ below).
+
+---
+
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Cross Works Engineering (Pty) Ltd
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+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/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@crossworks/client-types",
+  "version": "0.230.43",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossworks-engineering/mantle"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/aside-style.ts

@@ -0,0 +1,70 @@
+/**
+ * Aside — gradient styling helpers (the single source of truth for how an aside
+ * box is painted). Shared by the live editor NodeView (`aside-view.tsx`) and the
+ * server-side public renderer (`lib/render-page-doc.ts`) so an aside looks the
+ * same in both. Framework-free + pure (the random pickers run client-side only,
+ * on slash-insert / swatch-click), so this module is safe to import from a
+ * server file.
+ *
+ * The gradient is built from a SELECTED themed colour (`chart-1..5`, never a raw
+ * hex — themes redefine these vars) plus an `angle`. It blends the base colour
+ * into the cyclically-next chart colour and layers a soft radial glow whose
+ * corner tracks the angle, so each aside reads as a distinct, on-theme panel.
+ */
+
+export const ASIDE_COLORS = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5'] as const;
+export type AsideColor = (typeof ASIDE_COLORS)[number];
+
+export const DEFAULT_ASIDE_COLOR: AsideColor = 'chart-1';
+export const DEFAULT_ASIDE_ANGLE = 135;
+
+export function normalizeAsideColor(v: unknown): AsideColor {
+  return (ASIDE_COLORS as readonly string[]).includes(v as string)
+    ? (v as AsideColor)
+    : DEFAULT_ASIDE_COLOR;
+}
+
+/** Wrap any value into a clean 0–359 integer angle. */
+export function normalizeAsideAngle(v: unknown): number {
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return DEFAULT_ASIDE_ANGLE;
+  return ((n % 360) + 360) % 360;
+}
+
+/** The cyclically-next chart colour — the gradient's second stop. */
+function secondaryColor(color: AsideColor): AsideColor {
+  const i = ASIDE_COLORS.indexOf(color);
+  return ASIDE_COLORS[(i + 1) % ASIDE_COLORS.length]!;
+}
+
+const RADIAL_CORNERS = ['top left', 'top right', 'bottom right', 'bottom left'] as const;
+
+/**
+ * The full `background` shorthand for an aside: a soft radial glow (corner
+ * derived from the angle) layered over a directional two-tone wash. Uses
+ * `color-mix` + theme vars so it tracks the active theme and light/dark.
+ */
+export function asideBackground(color: AsideColor, angle: number): string {
+  const a = normalizeAsideAngle(angle);
+  const c1 = `var(--${color})`;
+  const c2 = `var(--${secondaryColor(color)})`;
+  const corner = RADIAL_CORNERS[Math.floor(a / 90) % 4]!;
+  const radial = `radial-gradient(circle at ${corner}, color-mix(in oklab, ${c2} 22%, transparent), transparent 62%)`;
+  const linear = `linear-gradient(${a}deg, color-mix(in oklab, ${c1} 16%, transparent), color-mix(in oklab, ${c2} 7%, transparent))`;
+  return `${radial}, ${linear}`;
+}
+
+/** A faint themed border that pairs with the gradient fill. */
+export function asideBorderColor(color: AsideColor): string {
+  return `color-mix(in oklab, var(--${color}) 30%, transparent)`;
+}
+
+/** Random themed colour — used when inserting a fresh aside (client-side only). */
+export function randomAsideColor(): AsideColor {
+  return ASIDE_COLORS[Math.floor(Math.random() * ASIDE_COLORS.length)]!;
+}
+
+/** Random gradient angle — used when inserting / reshuffling (client-side only). */
+export function randomAsideAngle(): number {
+  return Math.floor(Math.random() * 360);
+}

package/src/assistant-limits.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { ASSISTANT_TURN_MAX_CHARS, longMessageNoteTitle } from './assistant-limits';
+
+describe('ASSISTANT_TURN_MAX_CHARS', () => {
+  it('is the number the turn route validates against', () => {
+    // Pinned deliberately: the composer offloads at this number and the route
+    // rejects above it. If they ever drift, a long paste 400s again.
+    expect(ASSISTANT_TURN_MAX_CHARS).toBe(20_000);
+  });
+});
+
+describe('longMessageNoteTitle', () => {
+  it('uses the first non-empty line', () => {
+    expect(longMessageNoteTitle('Feature Upgrade Roadmap\n\nbody text')).toBe(
+      'Feature Upgrade Roadmap',
+    );
+  });
+
+  it('skips leading blank lines', () => {
+    expect(longMessageNoteTitle('\n\n   \nThe actual title\nmore')).toBe('The actual title');
+  });
+
+  it('strips markdown heading, bullet and ordered-item punctuation', () => {
+    expect(longMessageNoteTitle('### Phase 2 — Size S/L')).toBe('Phase 2 — Size S/L');
+    expect(longMessageNoteTitle('- a bulleted opener')).toBe('a bulleted opener');
+    expect(longMessageNoteTitle('> quoted opener')).toBe('quoted opener');
+    expect(longMessageNoteTitle('1. first step')).toBe('first step');
+  });
+
+  it('skips a bare code fence and takes the line after it', () => {
+    expect(longMessageNoteTitle('```json\n{"a":1}')).toBe('{"a":1}');
+  });
+
+  it('truncates to the notes API title limit with an ellipsis', () => {
+    const title = longMessageNoteTitle('x'.repeat(500));
+    expect(title).toHaveLength(200);
+    expect(title.endsWith('…')).toBe(true);
+  });
+
+  it('keeps a title exactly at the limit intact', () => {
+    expect(longMessageNoteTitle('y'.repeat(200))).toBe('y'.repeat(200));
+  });
+
+  it('falls back when there is no usable line', () => {
+    expect(longMessageNoteTitle('')).toBe('Long message');
+    expect(longMessageNoteTitle('\n\n  \n')).toBe('Long message');
+    expect(longMessageNoteTitle('```', 'Pasted text')).toBe('Pasted text');
+  });
+});

package/src/assistant-limits.ts

@@ -0,0 +1,41 @@
+/**
+ * The size ceiling on one assistant turn's text, shared by the composer and the
+ * route that validates it.
+ *
+ * It used to live only in the route's zod schema. The composer had no idea it
+ * existed, so pasting a long plan cleared the box, dropped the message from the
+ * transcript, and surfaced zod's own words — "Too big: expected string to have
+ * <=20000 characters" — in 10px type beside the composer. From the user's seat a
+ * message simply vanished, and since a rejected turn writes NOTHING to
+ * `assistant_messages`, the whole failure was invisible server-side too. Both
+ * ends now read the same number, and the composer offloads rather than fails.
+ */
+
+/** Max characters accepted for one turn's `text` — INCLUDING the context
+ *  preamble and focus directive the composer appends, which is what the route
+ *  actually measures. */
+export const ASSISTANT_TURN_MAX_CHARS = 20_000;
+
+/** Longest title the notes API accepts (`POST /api/notes`). */
+const NOTE_TITLE_MAX = 200;
+
+/**
+ * A note title for an offloaded over-long message: its first non-empty line,
+ * trimmed of markdown heading/quote/list punctuation so the title reads as
+ * prose. Falls back to a generic label when the body opens with no usable line
+ * (a bare code fence, say).
+ */
+export function longMessageNoteTitle(body: string, fallback = 'Long message'): string {
+  for (const raw of body.split('\n')) {
+    const line = raw
+      .trim()
+      .replace(/^#{1,6}\s+/, '') // heading
+      .replace(/^[>*+-]\s+/, '') // quote / bullet
+      .replace(/^\d+[.)]\s+/, '') // ordered item
+      .replace(/^```.*$/, '') // fence opener
+      .trim();
+    if (!line) continue;
+    return line.length > NOTE_TITLE_MAX ? `${line.slice(0, NOTE_TITLE_MAX - 1)}…` : line;
+  }
+  return fallback;
+}