@almadar/extensions 1.0.13

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Virtual Document — The TypeScript Wrapper Trick
+ *
+ * Wraps .orb JSON content inside a TypeScript file that imports
+ * OrbitalSchema from @almadar/core. This lets the TypeScript
+ * language server validate the entire .orb structure for free.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Number of lines the prefix adds before .orb content begins.
+ * Used to offset diagnostics back to original .orb line numbers.
+ *
+ * The prefix is exactly 2 lines:
+ *   Line 1: import type { OrbitalSchema } from '@almadar/core';
+ *   Line 2: const _orbital = ... (the .orb content starts on THIS line)
+ *
+ * So .orb line 1 corresponds to virtual .ts line 2.
+ */
+declare const WRAPPER_LINE_OFFSET = 1;
+/**
+ * Number of characters on the prefix line before .orb content begins.
+ * `const _orbital = ` is 18 characters.
+ */
+declare const WRAPPER_COL_OFFSET = 18;
+/**
+ * Wrap raw .orb JSON content into a virtual TypeScript file.
+ *
+ * @param orbContent - The raw JSON string from the .orb file
+ * @returns The complete TypeScript source that tsserver can validate
+ *
+ * @example
+ * ```ts
+ * const orbJson = fs.readFileSync('app.orb', 'utf-8');
+ * const tsContent = wrapOrbContent(orbJson);
+ * // tsContent is now a valid .ts file that TypeScript can check
+ * ```
+ */
+declare function wrapOrbContent(orbContent: string): string;
+/**
+ * Extract the original .orb content from a wrapped virtual TypeScript file.
+ *
+ * @param virtualContent - The virtual .ts file content
+ * @returns The original .orb JSON string, or null if not a valid wrapper
+ */
+declare function unwrapOrbContent(virtualContent: string): string | null;
+/**
+ * Generate the virtual .ts filename for a given .orb file path.
+ *
+ * @param orbFilePath - Absolute path to the .orb file
+ * @returns The virtual .ts file path (same directory, `.orb.ts` extension)
+ *
+ * @example
+ * ```ts
+ * getVirtualPath('/projects/app.orb')
+ * // → '/projects/app.orb.ts'
+ * ```
+ */
+declare function getVirtualPath(orbFilePath: string): string;
+
+/**
+ * Diagnostic Mapper
+ *
+ * Maps TypeScript diagnostics from the virtual .ts file back to
+ * the original .orb file positions, adjusting for the wrapper prefix.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A position in a text document (0-indexed line and character).
+ */
+interface Position {
+    /** 0-indexed line number */
+    line: number;
+    /** 0-indexed character offset within the line */
+    character: number;
+}
+/**
+ * A range in a text document.
+ */
+interface Range {
+    start: Position;
+    end: Position;
+}
+/**
+ * Severity levels matching both VSCode and Zed conventions.
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
+/**
+ * An editor-agnostic diagnostic — the universal unit that
+ * VSCode and Zed extensions translate into their native format.
+ */
+interface OrbDiagnostic {
+    /** Human-readable error message */
+    message: string;
+    /** Location in the .orb file (already adjusted from virtual .ts) */
+    range: Range;
+    /** Severity level */
+    severity: DiagnosticSeverity;
+    /** TypeScript error code (e.g. 2322, 2353) for filtering */
+    code?: number;
+    /** Source identifier */
+    source: 'almadar-ts';
+}
+/**
+ * Raw TypeScript diagnostic (minimal shape matching ts.Diagnostic).
+ * Extensions should map their TS server output to this shape.
+ */
+interface TsDiagnostic {
+    /** 0-indexed line in the virtual .ts file */
+    line: number;
+    /** 0-indexed character in the virtual .ts file */
+    character: number;
+    /** End line (optional, defaults to same as line) */
+    endLine?: number;
+    /** End character (optional) */
+    endCharacter?: number;
+    /** Error message text */
+    messageText: string;
+    /** TS error code */
+    code?: number;
+    /** 1 = error, 2 = warning, 3 = info, 4 = hint */
+    category?: number;
+}
+/**
+ * Map a virtual .ts file position back to the original .orb position.
+ *
+ * @param virtualLine - 0-indexed line in the virtual .ts file
+ * @param virtualChar - 0-indexed character in the virtual .ts file
+ * @returns Adjusted position in the .orb file
+ */
+declare function mapPositionToOrb(virtualLine: number, virtualChar: number): Position;
+/**
+ * Map a single TypeScript diagnostic to an OrbDiagnostic.
+ *
+ * @param tsDiag - The raw TypeScript diagnostic
+ * @returns An editor-agnostic diagnostic with adjusted positions
+ */
+declare function mapDiagnostic(tsDiag: TsDiagnostic): OrbDiagnostic;
+/**
+ * Map an array of TypeScript diagnostics to OrbDiagnostics.
+ * Filters out diagnostics that fall within the wrapper prefix.
+ *
+ * @param diagnostics - Array of raw TypeScript diagnostics
+ * @returns Array of editor-agnostic diagnostics
+ */
+declare function mapDiagnostics(diagnostics: TsDiagnostic[]): OrbDiagnostic[];
+
+/**
+ * S-Expression Grammar Generator
+ *
+ * Generates a TextMate injection grammar for S-expression syntax
+ * highlighting inside .orb files. The grammar is derived from
+ * @almadar/operators — the single source of truth for all operator names.
+ *
+ * This means new operators automatically get highlighting when
+ * the package is rebuilt. No manual grammar maintenance.
+ *
+ * @packageDocumentation
+ */
+/**
+ * TextMate grammar rule
+ */
+interface TmRule {
+    name: string;
+    match: string;
+}
+/**
+ * TextMate injection grammar structure
+ */
+interface TmInjectionGrammar {
+    scopeName: string;
+    injectionSelector: string;
+    patterns: TmRule[];
+}
+/**
+ * Generate a TextMate injection grammar for S-expression highlighting.
+ *
+ * The grammar injects into `.orb` files (JSON scope) and highlights:
+ * - **Operators** by category (arithmetic, effect, control, etc.)
+ * - **Bindings** (`@entity.field`, `@payload.value`)
+ * - **Events** (UPPER_CASE_NAMES)
+ *
+ * @returns A complete TextMate injection grammar object
+ *
+ * @example
+ * ```ts
+ * import { generateSExprGrammar } from '@almadar/extensions';
+ * import { writeFileSync } from 'fs';
+ *
+ * const grammar = generateSExprGrammar();
+ * writeFileSync('sexpr.injection.json', JSON.stringify(grammar, null, 2));
+ * ```
+ */
+declare function generateSExprGrammar(): TmInjectionGrammar;
+/**
+ * Serialize the grammar to a formatted JSON string.
+ * Ready to be written to `sexpr.injection.json`.
+ */
+declare function generateSExprGrammarJson(): string;
+/**
+ * Get a flat list of all operator names from the registry.
+ * Useful for editor extensions that need the operator list without
+ * importing @almadar/operators directly.
+ */
+declare function getOperatorNames(): string[];
+/**
+ * Get operators grouped by category.
+ * Useful for autocomplete that groups suggestions by category.
+ */
+declare function getOperatorsByCategory(): Record<string, string[]>;
+
+export { type DiagnosticSeverity, type OrbDiagnostic, type Position, type Range, type TmInjectionGrammar, type TsDiagnostic, WRAPPER_COL_OFFSET, WRAPPER_LINE_OFFSET, generateSExprGrammar, generateSExprGrammarJson, getOperatorNames, getOperatorsByCategory, getVirtualPath, mapDiagnostic, mapDiagnostics, mapPositionToOrb, unwrapOrbContent, wrapOrbContent };

package/dist/index.js

@@ -0,0 +1,143 @@
+import { OPERATOR_NAMES, OPERATORS } from '@almadar/operators';
+
+// src/virtual-document.ts
+var TS_PREFIX = `import type { OrbitalSchema } from '@almadar/core';
+const _orbital = `;
+var TS_SUFFIX = ` satisfies OrbitalSchema;
+`;
+var WRAPPER_LINE_OFFSET = 1;
+var WRAPPER_COL_OFFSET = 18;
+function wrapOrbContent(orbContent) {
+  return TS_PREFIX + orbContent + TS_SUFFIX;
+}
+function unwrapOrbContent(virtualContent) {
+  if (!virtualContent.startsWith(TS_PREFIX)) return null;
+  if (!virtualContent.endsWith(TS_SUFFIX)) return null;
+  return virtualContent.slice(
+    TS_PREFIX.length,
+    virtualContent.length - TS_SUFFIX.length
+  );
+}
+function getVirtualPath(orbFilePath) {
+  return orbFilePath + ".ts";
+}
+
+// src/diagnostic-mapper.ts
+function mapPositionToOrb(virtualLine, virtualChar) {
+  const orbLine = virtualLine - WRAPPER_LINE_OFFSET;
+  const orbChar = orbLine === 0 ? Math.max(0, virtualChar - WRAPPER_COL_OFFSET) : virtualChar;
+  return {
+    line: Math.max(0, orbLine),
+    character: Math.max(0, orbChar)
+  };
+}
+function mapDiagnostic(tsDiag) {
+  const start = mapPositionToOrb(tsDiag.line, tsDiag.character);
+  const end = mapPositionToOrb(
+    tsDiag.endLine ?? tsDiag.line,
+    tsDiag.endCharacter ?? tsDiag.character + 1
+  );
+  const severityMap = {
+    1: "error",
+    2: "warning",
+    3: "info",
+    4: "hint"
+  };
+  return {
+    message: cleanTsMessage(tsDiag.messageText),
+    range: { start, end },
+    severity: severityMap[tsDiag.category ?? 1] ?? "error",
+    code: tsDiag.code,
+    source: "almadar-ts"
+  };
+}
+function mapDiagnostics(diagnostics) {
+  return diagnostics.filter((d) => d.line >= WRAPPER_LINE_OFFSET).map(mapDiagnostic);
+}
+function cleanTsMessage(message) {
+  return message.replace(/_orbital/g, ".orb file").replace(/Type '([^']+)'/g, "Value '$1'");
+}
+var CATEGORY_SCOPES = {
+  // Core language
+  arithmetic: "keyword.operator.arithmetic.sexpr",
+  comparison: "keyword.operator.comparison.sexpr",
+  logic: "keyword.operator.logical.sexpr",
+  control: "keyword.control.sexpr",
+  effect: "keyword.other.effect.sexpr",
+  collection: "support.function.collection.sexpr",
+  // Standard library
+  "std-math": "support.function.math.sexpr",
+  "std-str": "support.function.string.sexpr",
+  "std-array": "support.function.array.sexpr",
+  "std-object": "support.function.object.sexpr",
+  "std-time": "support.function.time.sexpr",
+  "std-validate": "support.function.validate.sexpr",
+  "std-format": "support.function.format.sexpr",
+  "std-async": "support.function.async.sexpr",
+  "std-nn": "support.function.nn.sexpr",
+  "std-tensor": "support.function.tensor.sexpr",
+  "std-train": "support.function.train.sexpr"
+};
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function groupOperatorsByScope() {
+  const groups = /* @__PURE__ */ new Map();
+  for (const name of OPERATOR_NAMES) {
+    const meta = OPERATORS[name];
+    const category = meta?.category ?? "effect";
+    const scope = CATEGORY_SCOPES[category] ?? "keyword.other.sexpr";
+    if (!groups.has(scope)) groups.set(scope, []);
+    groups.get(scope).push(name);
+  }
+  return groups;
+}
+function generateSExprGrammar() {
+  const patterns = [];
+  const groups = groupOperatorsByScope();
+  for (const [scope, names] of groups) {
+    const sorted = [...names].sort((a, b) => b.length - a.length);
+    const alternation = sorted.map(escapeRegex).join("|");
+    patterns.push({
+      name: scope,
+      match: `(?<=")(${alternation})(?=")`
+    });
+  }
+  patterns.push({
+    name: "variable.other.binding.sexpr",
+    match: '(?<=")@(entity|payload|context|config)\\.[a-zA-Z_][a-zA-Z0-9_.]*(?=")'
+  });
+  patterns.push({
+    name: "constant.other.event.sexpr",
+    match: '(?<=")[A-Z][A-Z0-9_]{2,}(?=")'
+  });
+  patterns.push({
+    name: "entity.name.tag.slot.sexpr",
+    match: '(?<=")(main|sidebar|modal|drawer|overlay|center|toast|hud-top|hud-bottom|floating|system)(?=")'
+  });
+  return {
+    scopeName: "source.orb.sexpr-injection",
+    injectionSelector: "L:source.orb -comment",
+    patterns
+  };
+}
+function generateSExprGrammarJson() {
+  return JSON.stringify(generateSExprGrammar(), null, 2);
+}
+function getOperatorNames() {
+  return [...OPERATOR_NAMES];
+}
+function getOperatorsByCategory() {
+  const result = {};
+  for (const name of OPERATOR_NAMES) {
+    const meta = OPERATORS[name];
+    const category = meta?.category ?? "unknown";
+    if (!result[category]) result[category] = [];
+    result[category].push(name);
+  }
+  return result;
+}
+
+export { WRAPPER_COL_OFFSET, WRAPPER_LINE_OFFSET, generateSExprGrammar, generateSExprGrammarJson, getOperatorNames, getOperatorsByCategory, getVirtualPath, mapDiagnostic, mapDiagnostics, mapPositionToOrb, unwrapOrbContent, wrapOrbContent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/virtual-document.ts","../src/diagnostic-mapper.ts","../src/sexpr-grammar.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Virtual Document — The TypeScript Wrapper Trick\n *\n * Wraps .orb JSON content inside a TypeScript file that imports\n * OrbitalSchema from @almadar/core. This lets the TypeScript\n * language server validate the entire .orb structure for free.\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// Constants\n// ============================================================================\n\n/**\n * The TypeScript prefix prepended to .orb content.\n * Line 1: import type\n * Line 2: const declaration with `satisfies` for best error messages\n */\nconst TS_PREFIX =\n    `import type { OrbitalSchema } from '@almadar/core';\\n` +\n    `const _orbital = `;\n\n/**\n * The TypeScript suffix appended after .orb content.\n */\nconst TS_SUFFIX = ` satisfies OrbitalSchema;\\n`;\n\n/**\n * Number of lines the prefix adds before .orb content begins.\n * Used to offset diagnostics back to original .orb line numbers.\n *\n * The prefix is exactly 2 lines:\n *   Line 1: import type { OrbitalSchema } from '@almadar/core';\n *   Line 2: const _orbital = ... (the .orb content starts on THIS line)\n *\n * So .orb line 1 corresponds to virtual .ts line 2.\n */\nexport const WRAPPER_LINE_OFFSET = 1;\n\n/**\n * Number of characters on the prefix line before .orb content begins.\n * `const _orbital = ` is 18 characters.\n */\nexport const WRAPPER_COL_OFFSET = 18;\n\n// ============================================================================\n// Core API\n// ============================================================================\n\n/**\n * Wrap raw .orb JSON content into a virtual TypeScript file.\n *\n * @param orbContent - The raw JSON string from the .orb file\n * @returns The complete TypeScript source that tsserver can validate\n *\n * @example\n * ```ts\n * const orbJson = fs.readFileSync('app.orb', 'utf-8');\n * const tsContent = wrapOrbContent(orbJson);\n * // tsContent is now a valid .ts file that TypeScript can check\n * ```\n */\nexport function wrapOrbContent(orbContent: string): string {\n    return TS_PREFIX + orbContent + TS_SUFFIX;\n}\n\n/**\n * Extract the original .orb content from a wrapped virtual TypeScript file.\n *\n * @param virtualContent - The virtual .ts file content\n * @returns The original .orb JSON string, or null if not a valid wrapper\n */\nexport function unwrapOrbContent(virtualContent: string): string | null {\n    if (!virtualContent.startsWith(TS_PREFIX)) return null;\n    if (!virtualContent.endsWith(TS_SUFFIX)) return null;\n\n    return virtualContent.slice(\n        TS_PREFIX.length,\n        virtualContent.length - TS_SUFFIX.length,\n    );\n}\n\n/**\n * Generate the virtual .ts filename for a given .orb file path.\n *\n * @param orbFilePath - Absolute path to the .orb file\n * @returns The virtual .ts file path (same directory, `.orb.ts` extension)\n *\n * @example\n * ```ts\n * getVirtualPath('/projects/app.orb')\n * // → '/projects/app.orb.ts'\n * ```\n */\nexport function getVirtualPath(orbFilePath: string): string {\n    return orbFilePath + '.ts';\n}\n","/**\n * Diagnostic Mapper\n *\n * Maps TypeScript diagnostics from the virtual .ts file back to\n * the original .orb file positions, adjusting for the wrapper prefix.\n *\n * @packageDocumentation\n */\n\nimport { WRAPPER_LINE_OFFSET, WRAPPER_COL_OFFSET } from './virtual-document.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * A position in a text document (0-indexed line and character).\n */\nexport interface Position {\n    /** 0-indexed line number */\n    line: number;\n    /** 0-indexed character offset within the line */\n    character: number;\n}\n\n/**\n * A range in a text document.\n */\nexport interface Range {\n    start: Position;\n    end: Position;\n}\n\n/**\n * Severity levels matching both VSCode and Zed conventions.\n */\nexport type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';\n\n/**\n * An editor-agnostic diagnostic — the universal unit that\n * VSCode and Zed extensions translate into their native format.\n */\nexport interface OrbDiagnostic {\n    /** Human-readable error message */\n    message: string;\n    /** Location in the .orb file (already adjusted from virtual .ts) */\n    range: Range;\n    /** Severity level */\n    severity: DiagnosticSeverity;\n    /** TypeScript error code (e.g. 2322, 2353) for filtering */\n    code?: number;\n    /** Source identifier */\n    source: 'almadar-ts';\n}\n\n/**\n * Raw TypeScript diagnostic (minimal shape matching ts.Diagnostic).\n * Extensions should map their TS server output to this shape.\n */\nexport interface TsDiagnostic {\n    /** 0-indexed line in the virtual .ts file */\n    line: number;\n    /** 0-indexed character in the virtual .ts file */\n    character: number;\n    /** End line (optional, defaults to same as line) */\n    endLine?: number;\n    /** End character (optional) */\n    endCharacter?: number;\n    /** Error message text */\n    messageText: string;\n    /** TS error code */\n    code?: number;\n    /** 1 = error, 2 = warning, 3 = info, 4 = hint */\n    category?: number;\n}\n\n// ============================================================================\n// Core API\n// ============================================================================\n\n/**\n * Map a virtual .ts file position back to the original .orb position.\n *\n * @param virtualLine - 0-indexed line in the virtual .ts file\n * @param virtualChar - 0-indexed character in the virtual .ts file\n * @returns Adjusted position in the .orb file\n */\nexport function mapPositionToOrb(\n    virtualLine: number,\n    virtualChar: number,\n): Position {\n    const orbLine = virtualLine - WRAPPER_LINE_OFFSET;\n\n    // If on the same line as the wrapper prefix, adjust column\n    const orbChar =\n        orbLine === 0 ? Math.max(0, virtualChar - WRAPPER_COL_OFFSET) : virtualChar;\n\n    return {\n        line: Math.max(0, orbLine),\n        character: Math.max(0, orbChar),\n    };\n}\n\n/**\n * Map a single TypeScript diagnostic to an OrbDiagnostic.\n *\n * @param tsDiag - The raw TypeScript diagnostic\n * @returns An editor-agnostic diagnostic with adjusted positions\n */\nexport function mapDiagnostic(tsDiag: TsDiagnostic): OrbDiagnostic {\n    const start = mapPositionToOrb(tsDiag.line, tsDiag.character);\n    const end = mapPositionToOrb(\n        tsDiag.endLine ?? tsDiag.line,\n        tsDiag.endCharacter ?? tsDiag.character + 1,\n    );\n\n    const severityMap: Record<number, DiagnosticSeverity> = {\n        1: 'error',\n        2: 'warning',\n        3: 'info',\n        4: 'hint',\n    };\n\n    return {\n        message: cleanTsMessage(tsDiag.messageText),\n        range: { start, end },\n        severity: severityMap[tsDiag.category ?? 1] ?? 'error',\n        code: tsDiag.code,\n        source: 'almadar-ts',\n    };\n}\n\n/**\n * Map an array of TypeScript diagnostics to OrbDiagnostics.\n * Filters out diagnostics that fall within the wrapper prefix.\n *\n * @param diagnostics - Array of raw TypeScript diagnostics\n * @returns Array of editor-agnostic diagnostics\n */\nexport function mapDiagnostics(diagnostics: TsDiagnostic[]): OrbDiagnostic[] {\n    return diagnostics\n        .filter((d) => d.line >= WRAPPER_LINE_OFFSET)\n        .map(mapDiagnostic);\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/**\n * Clean up TypeScript error messages for .orb context.\n *\n * - Removes references to `_orbital` variable name\n * - Replaces `OrbitalSchema` with `.orb schema` for clarity\n */\nfunction cleanTsMessage(message: string): string {\n    return message\n        .replace(/_orbital/g, '.orb file')\n        .replace(/Type '([^']+)'/g, 'Value \\'$1\\'');\n}\n","/**\n * S-Expression Grammar Generator\n *\n * Generates a TextMate injection grammar for S-expression syntax\n * highlighting inside .orb files. The grammar is derived from\n * @almadar/operators — the single source of truth for all operator names.\n *\n * This means new operators automatically get highlighting when\n * the package is rebuilt. No manual grammar maintenance.\n *\n * @packageDocumentation\n */\n\nimport {\n    OPERATOR_NAMES,\n    OPERATORS,\n    type OperatorMeta,\n    type OperatorCategory,\n} from '@almadar/operators';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * TextMate grammar rule\n */\ninterface TmRule {\n    name: string;\n    match: string;\n}\n\n/**\n * TextMate injection grammar structure\n */\nexport interface TmInjectionGrammar {\n    scopeName: string;\n    injectionSelector: string;\n    patterns: TmRule[];\n}\n\n// ============================================================================\n// Category → Scope Mapping\n// ============================================================================\n\n/**\n * Maps operator categories to TextMate scopes for semantic coloring.\n */\nconst CATEGORY_SCOPES: Record<string, string> = {\n    // Core language\n    arithmetic: 'keyword.operator.arithmetic.sexpr',\n    comparison: 'keyword.operator.comparison.sexpr',\n    logic: 'keyword.operator.logical.sexpr',\n    control: 'keyword.control.sexpr',\n    effect: 'keyword.other.effect.sexpr',\n    collection: 'support.function.collection.sexpr',\n\n    // Standard library\n    'std-math': 'support.function.math.sexpr',\n    'std-str': 'support.function.string.sexpr',\n    'std-array': 'support.function.array.sexpr',\n    'std-object': 'support.function.object.sexpr',\n    'std-time': 'support.function.time.sexpr',\n    'std-validate': 'support.function.validate.sexpr',\n    'std-format': 'support.function.format.sexpr',\n    'std-async': 'support.function.async.sexpr',\n    'std-nn': 'support.function.nn.sexpr',\n    'std-tensor': 'support.function.tensor.sexpr',\n    'std-train': 'support.function.train.sexpr',\n};\n\n// ============================================================================\n// Grammar Generation\n// ============================================================================\n\n/**\n * Escape a string for use in a TextMate regex pattern.\n */\nfunction escapeRegex(str: string): string {\n    return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Group operator names by their TextMate scope.\n */\nfunction groupOperatorsByScope(): Map<string, string[]> {\n    const groups = new Map<string, string[]>();\n\n    for (const name of OPERATOR_NAMES) {\n        const meta: OperatorMeta | undefined = OPERATORS[name];\n        const category = meta?.category ?? 'effect';\n        const scope = CATEGORY_SCOPES[category] ?? 'keyword.other.sexpr';\n\n        if (!groups.has(scope)) groups.set(scope, []);\n        groups.get(scope)!.push(name);\n    }\n\n    return groups;\n}\n\n/**\n * Generate a TextMate injection grammar for S-expression highlighting.\n *\n * The grammar injects into `.orb` files (JSON scope) and highlights:\n * - **Operators** by category (arithmetic, effect, control, etc.)\n * - **Bindings** (`@entity.field`, `@payload.value`)\n * - **Events** (UPPER_CASE_NAMES)\n *\n * @returns A complete TextMate injection grammar object\n *\n * @example\n * ```ts\n * import { generateSExprGrammar } from '@almadar/extensions';\n * import { writeFileSync } from 'fs';\n *\n * const grammar = generateSExprGrammar();\n * writeFileSync('sexpr.injection.json', JSON.stringify(grammar, null, 2));\n * ```\n */\nexport function generateSExprGrammar(): TmInjectionGrammar {\n    const patterns: TmRule[] = [];\n\n    // 1. Operator keywords grouped by category/scope\n    const groups = groupOperatorsByScope();\n    for (const [scope, names] of groups) {\n        // Sort by length descending so longer operators match first\n        const sorted = [...names].sort((a, b) => b.length - a.length);\n        const alternation = sorted.map(escapeRegex).join('|');\n\n        patterns.push({\n            name: scope,\n            match: `(?<=\")(${alternation})(?=\")`,\n        });\n    }\n\n    // 2. Bindings: @entity.field, @payload.value, @context.key\n    patterns.push({\n        name: 'variable.other.binding.sexpr',\n        match: '(?<=\")@(entity|payload|context|config)\\\\.[a-zA-Z_][a-zA-Z0-9_.]*(?=\")',\n    });\n\n    // 3. Events: UPPER_CASE identifiers (e.g. SELECT_UNIT, ATTACK)\n    patterns.push({\n        name: 'constant.other.event.sexpr',\n        match: '(?<=\")[A-Z][A-Z0-9_]{2,}(?=\")',\n    });\n\n    // 4. UI Slots: main, sidebar, modal, etc.\n    patterns.push({\n        name: 'entity.name.tag.slot.sexpr',\n        match: '(?<=\")(main|sidebar|modal|drawer|overlay|center|toast|hud-top|hud-bottom|floating|system)(?=\")',\n    });\n\n    return {\n        scopeName: 'source.orb.sexpr-injection',\n        injectionSelector: 'L:source.orb -comment',\n        patterns,\n    };\n}\n\n/**\n * Serialize the grammar to a formatted JSON string.\n * Ready to be written to `sexpr.injection.json`.\n */\nexport function generateSExprGrammarJson(): string {\n    return JSON.stringify(generateSExprGrammar(), null, 2);\n}\n\n/**\n * Get a flat list of all operator names from the registry.\n * Useful for editor extensions that need the operator list without\n * importing @almadar/operators directly.\n */\nexport function getOperatorNames(): string[] {\n    return [...OPERATOR_NAMES];\n}\n\n/**\n * Get operators grouped by category.\n * Useful for autocomplete that groups suggestions by category.\n */\nexport function getOperatorsByCategory(): Record<string, string[]> {\n    const result: Record<string, string[]> = {};\n\n    for (const name of OPERATOR_NAMES) {\n        const meta: OperatorMeta | undefined = OPERATORS[name];\n        const category = meta?.category ?? 'unknown';\n        if (!result[category]) result[category] = [];\n        result[category].push(name);\n    }\n\n    return result;\n}\n"]}

package/dist/sexpr.injection.json

@@ -0,0 +1,74 @@
+{
+  "scopeName": "source.orb.sexpr-injection",
+  "injectionSelector": "L:source.orb -comment",
+  "patterns": [
+    {
+      "name": "keyword.operator.arithmetic.sexpr",
+      "match": "(?<=\")(floor|round|clamp|ceil|abs|min|max|\\+|-|\\*|/|%)(?=\")"
+    },
+    {
+      "name": "keyword.operator.comparison.sexpr",
+      "match": "(?<=\")(!=|<=|>=|=|<|>)(?=\")"
+    },
+    {
+      "name": "keyword.operator.logical.sexpr",
+      "match": "(?<=\")(and|not|or|if)(?=\")"
+    },
+    {
+      "name": "keyword.control.sexpr",
+      "match": "(?<=\")(when|let|do|fn)(?=\")"
+    },
+    {
+      "name": "keyword.other.effect.sexpr",
+      "match": "(?<=\")(call-service|render-ui|navigate|persist|despawn|notify|spawn|emit|set)(?=\")"
+    },
+    {
+      "name": "support.function.collection.sexpr",
+      "match": "(?<=\")(includes|contains|average|filter|concat|count|first|empty|find|last|map|sum|nth)(?=\")"
+    },
+    {
+      "name": "support.function.math.sexpr",
+      "match": "(?<=\")(math/randomInt|math/default|math/random|math/clamp|math/floor|math/round|math/ceil|math/sqrt|math/sign|math/lerp|math/abs|math/min|math/max|math/pow|math/mod|math/map)(?=\")"
+    },
+    {
+      "name": "support.function.string.sexpr",
+      "match": "(?<=\")(str/startsWith|str/replaceAll|str/capitalize|str/includes|str/endsWith|str/template|str/truncate|str/replace|str/reverse|str/default|str/concat|str/repeat|str/upper|str/lower|str/slice|str/split|str/trim|str/join|str/len)(?=\")"
+    },
+    {
+      "name": "support.function.array.sexpr",
+      "match": "(?<=\")(array/partition|array/findIndex|array/includes|array/dropLast|array/takeLast|array/reverse|array/flatten|array/groupBy|array/prepend|array/shuffle|array/indexOf|array/filter|array/reduce|array/concat|array/unique|array/append|array/insert|array/remove|array/reject|array/repeat|array/every|array/first|array/slice|array/range|array/find|array/some|array/last|array/sort|array/take|array/drop|array/len|array/map|array/nth|array/sum|array/avg|array/min|array/max|array/zip)(?=\")"
+    },
+    {
+      "name": "support.function.object.sexpr",
+      "match": "(?<=\")(object/entries|object/values|object/equals|object/filter|object/merge|object/clone|object/keys|object/pick|object/omit|object/get|object/set|object/has)(?=\")"
+    },
+    {
+      "name": "support.function.time.sexpr",
+      "match": "(?<=\")(time/subtract|time/isBefore|time/isFuture|time/isAfter|time/weekday|time/format|time/isPast|time/minute|time/today|time/parse|time/month|time/diff|time/year|time/hour|time/now|time/add|time/day)(?=\")"
+    },
+    {
+      "name": "support.function.validate.sexpr",
+      "match": "(?<=\")(validate/minLength|validate/maxLength|validate/required|validate/pattern|validate/length|validate/equals|validate/email|validate/phone|validate/range|validate/oneOf|validate/check|validate/uuid|validate/url|validate/min|validate/max)(?=\")"
+    },
+    {
+      "name": "support.function.format.sexpr",
+      "match": "(?<=\")(format/currency|format/percent|format/ordinal|format/number|format/plural|format/bytes|format/phone|format/list)(?=\")"
+    },
+    {
+      "name": "support.function.async.sexpr",
+      "match": "(?<=\")(async/debounce|async/throttle|async/sequence|async/timeout|async/delay|async/retry|async/race|async/all)(?=\")"
+    },
+    {
+      "name": "variable.other.binding.sexpr",
+      "match": "(?<=\")@(entity|payload|context|config)\\.[a-zA-Z_][a-zA-Z0-9_.]*(?=\")"
+    },
+    {
+      "name": "constant.other.event.sexpr",
+      "match": "(?<=\")[A-Z][A-Z0-9_]{2,}(?=\")"
+    },
+    {
+      "name": "entity.name.tag.slot.sexpr",
+      "match": "(?<=\")(main|sidebar|modal|drawer|overlay|center|toast|hud-top|hud-bottom|floating|system)(?=\")"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@almadar/extensions",
+  "version": "1.0.13",
+  "description": "Editor extension utilities for .orb files — virtual document wrapper and S-expression grammar generator",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@almadar/core": "1.0.13",
+    "@almadar/operators": "1.0.13"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/almadar-io/almadar.git",
+    "directory": "packages/almadar-extensions"
+  },
+  "license": "MIT",
+  "keywords": [
+    "almadar",
+    "orbital",
+    "editor",
+    "extensions",
+    "vscode",
+    "zed"
+  ],
+  "scripts": {
+    "build": "tsup && pnpm run generate-grammar && pnpm run build:editors",
+    "build:core": "tsup && pnpm run generate-grammar",
+    "build:watch": "tsup --watch",
+    "build:editors": "pnpm run build:lsp && pnpm run build:vscode && pnpm run build:zed",
+    "build:vscode": "cd editors/vscode && npm install --ignore-scripts 2>/dev/null; node esbuild.js && cp ../../dist/sexpr.injection.json syntaxes/sexpr.injection.json",
+    "build:zed": "mkdir -p editors/zed/syntaxes && cp dist/sexpr.injection.json editors/zed/syntaxes/sexpr.injection.json",
+    "build:lsp": "cd lsp && npm install --ignore-scripts 2>/dev/null; npx tsup",
+    "typecheck": "tsc --noEmit",
+    "generate-grammar": "tsx scripts/build-grammars.ts"
+  }
+}