@weave-apps/sdk 0.3.0 → 0.5.0

package/README.md

@@ -82,12 +82,14 @@ Official SDK for building third-party applications for the Weave Platform.
 ### 1. Initialize a New App
 
 ```bash
-npx weave-init my-custom-app
+npx @weave-apps/sdk my-custom-app
 cd my-custom-app
 npm install
 npm run build
 ```
 
+> **Note:** Running `npm install` will automatically create a `WEAVE_SPEC.md` file in your project root. This is an AI assistant guide for building Weave apps and is kept up to date each time you install or update the SDK.
+
 ### 2. Develop Your App
 
 Edit `src/app.ts`:

package/bin/init.js

@@ -33,13 +33,13 @@ if (appName === '--help') {
 🚀 Weave Apps SDK Help
 
 Usage:
-  weave-init <app-name>     Create a new Weave app
-  weave-init --help         Show this help message
+  npx @weave-apps/sdk <app-name>     Create a new Weave app
+  npx @weave-apps/sdk --help         Show this help message
 
 Examples:
-  weave-init my-app
-  weave-init my-custom-app
-  weave-init dashboard
+  npx @weave-apps/sdk my-app
+  npx @weave-apps/sdk my-custom-app
+  npx @weave-apps/sdk dashboard
 
 Requirements:
   • App name must be in kebab-case (lowercase with hyphens)
@@ -59,7 +59,7 @@ Learn more:
 
 if (!appName) {
   console.error('❌ Error: App name is required');
-  console.log('Usage: npx weave-init <app-name>');
+  console.log('Usage: npx @weave-apps/sdk <app-name>');
   process.exit(1);
 }
 
@@ -254,14 +254,8 @@ if (fs.existsSync(readmePath)) {
   console.warn('⚠️  Warning: README.md template not found in SDK templates');
 }
 
-// Copy WEAVE_SPEC.md from SDK templates
-const specPath = path.join(__dirname, '..', 'templates', 'WEAVE_SPEC.md');
-if (fs.existsSync(specPath)) {
-  const specContent = fs.readFileSync(specPath, 'utf8');
-  fs.writeFileSync(path.join(projectDir, 'WEAVE_SPEC.md'), specContent);
-} else {
-  console.warn('⚠️  Warning: WEAVE_SPEC.md not found in SDK templates');
-}
+// WEAVE_SPEC.md is automatically copied/updated by the SDK's postinstall script
+// each time the consumer runs npm install. It does not need to be copied here.
 
 // Create .gitignore
 const gitignore = `node_modules/
@@ -279,11 +273,10 @@ console.log('   ├── src/');
 console.log('   │   └── app.ts');
 console.log('   ├── package.json');
 console.log('   ├── tsconfig.json (extends SDK config)');
-console.log('   ├── WEAVE_SPEC.md (AI assistant guide)');
 console.log('   └── README.md\n');
 console.log('🚀 Next steps:');
 console.log(`   cd ${appName}`);
-console.log('   npm install');
+console.log('   npm install          # also creates WEAVE_SPEC.md (AI assistant guide)');
 console.log('   npm run build\n');
 
 // Helper functions

package/bin/postinstall.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @weave-apps/sdk
+ *
+ * Automatically copies/updates WEAVE_SPEC.md into the consumer's project
+ * root every time the SDK is installed or updated.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Core postinstall logic. Copies WEAVE_SPEC.md from the SDK templates
+ * directory into the consumer project root.
+ *
+ * @param {string} sdkRoot - Absolute path to the SDK package root
+ * @returns {{ status: string, message: string }}
+ */
+function runPostinstall(sdkRoot) {
+  // When running as a postinstall hook inside node_modules/@weave-apps/sdk,
+  // the project root is three levels up: node_modules/@weave-apps/sdk/ -> project root
+  const projectRoot = path.resolve(sdkRoot, '..', '..', '..');
+
+  // Safety check: only run when installed as a dependency (not during SDK development)
+  const isInstalledAsDependency = sdkRoot.includes('node_modules');
+  if (!isInstalledAsDependency) {
+    return { status: 'skipped', message: 'Not installed as a dependency' };
+  }
+
+  // Safety check: ensure we resolved to a real project (has a package.json)
+  const consumerPackageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(consumerPackageJsonPath)) {
+    return { status: 'skipped', message: 'No consumer package.json found' };
+  }
+
+  const specSource = path.join(sdkRoot, 'templates', 'WEAVE_SPEC.md');
+  const specDest = path.join(projectRoot, 'WEAVE_SPEC.md');
+
+  if (!fs.existsSync(specSource)) {
+    return { status: 'skipped', message: 'WEAVE_SPEC.md template not found' };
+  }
+
+  try {
+    const specContent = fs.readFileSync(specSource, 'utf8');
+    fs.writeFileSync(specDest, specContent);
+    return { status: 'copied', message: 'WEAVE_SPEC.md updated to latest version' };
+  } catch (err) {
+    return { status: 'error', message: err.message };
+  }
+}
+
+// Run when executed directly (postinstall hook)
+if (require.main === module) {
+  const sdkRoot = path.join(__dirname, '..');
+  const result = runPostinstall(sdkRoot);
+
+  if (result.status === 'copied') {
+    console.log(`📋 @weave-apps/sdk: ${result.message}`);
+  } else if (result.status === 'error') {
+    console.warn(`⚠️  @weave-apps/sdk: Could not update WEAVE_SPEC.md: ${result.message}`);
+  }
+}
+
+module.exports = { runPostinstall };

package/bin/postinstall.test.js

@@ -0,0 +1,103 @@
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { runPostinstall } = require('./postinstall');
+
+const SPEC_CONTENT = '# Test WEAVE_SPEC content\nThis is the latest spec.';
+
+/**
+ * Creates a fake node_modules/@weave-apps/sdk directory structure
+ * inside a temporary directory to simulate a real consumer project.
+ *
+ * Returns { projectRoot, sdkRoot, cleanup }
+ */
+function createFakeProject({ withPackageJson = true, withSpecTemplate = true } = {}) {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'weave-postinstall-test-'));
+  const sdkRoot = path.join(projectRoot, 'node_modules', '@weave-apps', 'sdk');
+
+  // Create SDK directory structure
+  fs.mkdirSync(path.join(sdkRoot, 'templates'), { recursive: true });
+
+  if (withPackageJson) {
+    fs.writeFileSync(
+      path.join(projectRoot, 'package.json'),
+      JSON.stringify({ name: 'test-consumer', version: '1.0.0' })
+    );
+  }
+
+  if (withSpecTemplate) {
+    fs.writeFileSync(path.join(sdkRoot, 'templates', 'WEAVE_SPEC.md'), SPEC_CONTENT);
+  }
+
+  const cleanup = () => fs.rmSync(projectRoot, { recursive: true, force: true });
+
+  return { projectRoot, sdkRoot, cleanup };
+}
+
+describe('postinstall', () => {
+  let project;
+
+  afterEach(() => {
+    if (project) {
+      project.cleanup();
+      project = null;
+    }
+  });
+
+  it('copies WEAVE_SPEC.md to consumer project root when installed as dependency', () => {
+    project = createFakeProject();
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'copied');
+    const dest = path.join(project.projectRoot, 'WEAVE_SPEC.md');
+    assert.ok(fs.existsSync(dest), 'WEAVE_SPEC.md should exist in project root');
+    assert.equal(fs.readFileSync(dest, 'utf8'), SPEC_CONTENT);
+  });
+
+  it('overwrites existing WEAVE_SPEC.md with latest version', () => {
+    project = createFakeProject();
+    const dest = path.join(project.projectRoot, 'WEAVE_SPEC.md');
+
+    // Write an old version first
+    fs.writeFileSync(dest, '# Old spec content');
+
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'copied');
+    assert.equal(fs.readFileSync(dest, 'utf8'), SPEC_CONTENT);
+  });
+
+  it('skips when not installed as a dependency (SDK development)', () => {
+    // Use a path that does NOT contain "node_modules"
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'weave-postinstall-dev-'));
+    const fakeSdkRoot = path.join(tmpDir, 'frontends', 'app-sdk');
+    fs.mkdirSync(path.join(fakeSdkRoot, 'templates'), { recursive: true });
+    fs.writeFileSync(path.join(fakeSdkRoot, 'templates', 'WEAVE_SPEC.md'), SPEC_CONTENT);
+
+    const result = runPostinstall(fakeSdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /Not installed as a dependency/);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('skips when no consumer package.json found', () => {
+    project = createFakeProject({ withPackageJson: false });
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /No consumer package\.json found/);
+  });
+
+  it('skips when WEAVE_SPEC.md template is missing from SDK', () => {
+    project = createFakeProject({ withSpecTemplate: false });
+    const result = runPostinstall(project.sdkRoot);
+
+    assert.equal(result.status, 'skipped');
+    assert.match(result.message, /template not found/);
+  });
+});

package/dist/WeaveDOMAPI.d.ts

@@ -475,6 +475,29 @@ export declare class WeaveDOMAPI {
      * await weaveDOM.unwatchElement('weave-watcher-1');
      */
     unwatchElement(watcherId: string): Promise<void>;
+    /**
+     * Scroll an element into view on the parent page
+     *
+     * Abstraction over Element.scrollIntoView(). Accepts either a boolean
+     * `alignToTop` parameter or a `ScrollIntoViewOptions` object.
+     *
+     * @param selector - CSS selector for the element to scroll into view
+     * @param arg - Optional. A boolean (alignToTop) or a ScrollIntoViewOptions object.
+     *   - `true` (default): aligns the element to the top of the scrollable ancestor
+     *   - `false`: aligns the element to the bottom
+     *   - `ScrollIntoViewOptions`: e.g. `{ behavior: 'smooth', block: 'center' }`
+     *
+     * @example
+     * // Scroll element to top (default)
+     * await weaveDOM.scrollIntoView('#my-element');
+     *
+     * // Scroll element to bottom
+     * await weaveDOM.scrollIntoView('#my-element', false);
+     *
+     * // Scroll with smooth animation to center
+     * await weaveDOM.scrollIntoView('#my-element', { behavior: 'smooth', block: 'center' });
+     */
+    scrollIntoView(selector: string, arg?: boolean | ScrollIntoViewOptions): Promise<void>;
     /**
      * Show an alert dialog on the parent page
      *

package/dist/WeaveDOMAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WeaveDOMAPI.d.ts","sourceRoot":"","sources":["../src/WeaveDOMAPI.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0DH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,CAAC;IACF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,WAAW,EAAE,GAAG,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACrC,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE;YACN,OAAO,EAAE,MAAM,CAAC;YAChB,EAAE,EAAE,MAAM,CAAC;YACX,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;KACH,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE;IACzC,UAAU,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;IAClD,OAAO,EAAE,eAAe,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,KAAK,IAAI,CAAC;AAuBX;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,eAAe,CAGR;IAEf,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,qBAAqB,CAAsC;IACnE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,qBAAqB,CAAgD;IAC7E,OAAO,CAAC,6BAA6B,CAAwD;IAC7F,OAAO,CAAC,sBAAsB,CAAiD;IAC/E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAK;;IAM7B;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACI,OAAO,IAAI,IAAI;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IA8FtB;;OAEG;IACH,OAAO,CAAC,WAAW;IA4CnB;;OAEG;IACU,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAI9D;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAInE;;OAEG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvD;;OAEG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAOtF;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxD;;;;;;;;;;;;OAYG;IACU,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1D;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO5E;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxC;;OAEG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;OAEG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5F;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE;;OAEG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;OAEG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/E;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvF;;OAEG;IACU,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;;;;;;;;OAYG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1D;;;;OAIG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI7D;;;;OAIG;IACU,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/E;;OAEG;IACU,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,yBAAyB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,4BAA4B,EACtC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC;IAelB;;;;;;;;;OASG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,EAClC,cAAc,GAAE,OAAe,GAC9B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;OAGG;IACI,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAI7D;;OAEG;IACI,gBAAgB,IAAI,IAAI;IAI/B;;;OAGG;IACI,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAI3D;;OAEG;IACI,eAAe,IAAI,IAAI;IAQ9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,aAAa,CACxB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,oBAAoB,CAAC;QAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,MAAM,CAAC;IAqBlB;;;;;;;OAOG;IACU,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACU,YAAY,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,MAAM,CAAC;IAmBlB;;;;;;;OAOG;IACU,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D;;;;;;;;;;OAUG;IACU,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;;;;;;;;;;;;;OAgBG;IACU,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGxD;;AAED,wBAAiC"}
+{"version":3,"file":"WeaveDOMAPI.d.ts","sourceRoot":"","sources":["../src/WeaveDOMAPI.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6DH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,CAAC;IACF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,WAAW,EAAE,GAAG,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACrC,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE;YACN,OAAO,EAAE,MAAM,CAAC;YAChB,EAAE,EAAE,MAAM,CAAC;YACX,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;KACH,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,KAAK,IAAI,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE;IACzC,UAAU,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC;IAClD,OAAO,EAAE,eAAe,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,KAAK,IAAI,CAAC;AAuBX;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,eAAe,CAGR;IAEf,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,qBAAqB,CAAsC;IACnE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,qBAAqB,CAAgD;IAC7E,OAAO,CAAC,6BAA6B,CAAwD;IAC7F,OAAO,CAAC,sBAAsB,CAAiD;IAC/E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,gBAAgB,CAAK;;IAM7B;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACI,OAAO,IAAI,IAAI;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IA8FtB;;OAEG;IACH,OAAO,CAAC,WAAW;IA4CnB;;OAEG;IACU,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAI9D;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAInE;;OAEG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvD;;OAEG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAOtF;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxD;;;;;;;;;;;;OAYG;IACU,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1D;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO5E;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxC;;OAEG;IACU,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;OAEG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5F;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE;;OAEG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;OAEG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/E;;OAEG;IACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvF;;OAEG;IACU,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACU,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;;;;;;;;OAYG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1D;;;;OAIG;IACU,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI7D;;;;OAIG;IACU,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/E;;OAEG;IACU,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,yBAAyB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,4BAA4B,EACtC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC;IAelB;;;;;;;;;OASG;IACU,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,EAClC,cAAc,GAAE,OAAe,GAC9B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;OAGG;IACI,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAI7D;;OAEG;IACI,gBAAgB,IAAI,IAAI;IAI/B;;;OAGG;IACI,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAI3D;;OAEG;IACI,eAAe,IAAI,IAAI;IAQ9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,aAAa,CACxB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,oBAAoB,CAAC;QAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,MAAM,CAAC;IAqBlB;;;;;;;OAOG;IACU,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACU,YAAY,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,MAAM,CAAC;IAmBlB;;;;;;;OAOG;IACU,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,cAAc,CACzB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,OAAO,GAAG,qBAAqB,GACpC,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;;OAUG;IACU,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;;;;;;;;;;;;;OAgBG;IACU,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGxD;;AAED,wBAAiC"}

package/dist/WeaveDOMAPI.js

@@ -47,6 +47,8 @@ var DOMOperation;
     DOMOperation["UNWATCH_ELEMENT"] = "UNWATCH_ELEMENT";
     // Navigation operations
     DOMOperation["RELOAD_PAGE"] = "RELOAD_PAGE";
+    // Scroll operations
+    DOMOperation["SCROLL_INTO_VIEW"] = "SCROLL_INTO_VIEW";
     // Dialog operations
     DOMOperation["SHOW_ALERT"] = "SHOW_ALERT";
     DOMOperation["SHOW_CONFIRM"] = "SHOW_CONFIRM";
@@ -646,6 +648,41 @@ export class WeaveDOMAPI {
         });
     }
     // ============================================================================
+    // Scroll Operations
+    // ============================================================================
+    /**
+     * Scroll an element into view on the parent page
+     *
+     * Abstraction over Element.scrollIntoView(). Accepts either a boolean
+     * `alignToTop` parameter or a `ScrollIntoViewOptions` object.
+     *
+     * @param selector - CSS selector for the element to scroll into view
+     * @param arg - Optional. A boolean (alignToTop) or a ScrollIntoViewOptions object.
+     *   - `true` (default): aligns the element to the top of the scrollable ancestor
+     *   - `false`: aligns the element to the bottom
+     *   - `ScrollIntoViewOptions`: e.g. `{ behavior: 'smooth', block: 'center' }`
+     *
+     * @example
+     * // Scroll element to top (default)
+     * await weaveDOM.scrollIntoView('#my-element');
+     *
+     * // Scroll element to bottom
+     * await weaveDOM.scrollIntoView('#my-element', false);
+     *
+     * // Scroll with smooth animation to center
+     * await weaveDOM.scrollIntoView('#my-element', { behavior: 'smooth', block: 'center' });
+     */
+    async scrollIntoView(selector, arg) {
+        const payload = { selector };
+        if (typeof arg === 'boolean') {
+            payload.alignToTop = arg;
+        }
+        else if (typeof arg === 'object' && arg !== null) {
+            payload.options = arg;
+        }
+        return this.sendRequest(DOMOperation.SCROLL_INTO_VIEW, payload);
+    }
+    // ============================================================================
     // Dialog Operations
     // ============================================================================
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weave-apps/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SDK for building Weave Micro Apps",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,9 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node bin/postinstall.js",
+    "test": "node --test bin/*.test.js"
   },
   "keywords": [
     "weave",

package/templates/WEAVE_SPEC.md

@@ -2,6 +2,9 @@
 
 > **AI Assistant Guide**: This document provides the complete specification for building Weave applications. Use this as your reference when helping developers create apps.
 
+> **Note**: When you update the SDK in your project, this SPEC sheet will be overwritten with the latest version.
+
+
 ## Architecture Overview
 
 Weave apps are **Web Components** that run in an **iframe** inside a browser extension sidebar. They interact with two secure APIs:
@@ -2234,6 +2237,15 @@ await weaveDOM.removeElement('.old-element');
 await weaveDOM.clickElement('button#submit');
 await weaveDOM.clickElement('a.nav-item[href="/dashboard"]');
 await weaveDOM.clickElement('.custom-button');
+
+// Scroll an element into view (defaults to aligning to top)
+await weaveDOM.scrollIntoView('#my-element');
+
+// Scroll element to bottom of viewport
+await weaveDOM.scrollIntoView('#my-element', false);
+
+// Scroll with smooth animation to center
+await weaveDOM.scrollIntoView('#my-element', { behavior: 'smooth', block: 'center' });
 ```
 
 **Click Element Use Cases:**
@@ -2243,6 +2255,19 @@ await weaveDOM.clickElement('.custom-button');
 - Automate user interactions
 - Trigger form submissions
 
+**Scroll Into View Use Cases:**
+- Scroll to a specific section of the page
+- Bring an element into the viewport before interacting with it
+- Provide visual feedback during automated workflows
+- Navigate long pages to show relevant content
+
+**Example - Scroll to element then click:**
+```typescript
+// Scroll button into view with smooth animation, then click it
+await weaveDOM.scrollIntoView('button#submit', { behavior: 'smooth', block: 'center' });
+await weaveDOM.clickElement('button#submit');
+```
+
 **Example - Auto-click a button after form fill:**
 ```typescript
 // Fill form fields
@@ -4309,7 +4334,7 @@ customElements.define('page-title-editor', PageTitleEditor);
 ### DOM API Methods (`weaveDOM`)
 - **Read:** `query`, `queryAll`, `getText`, `getAttribute`, `getValue`, `hasClass`, `getPageUrl`
 - **Write:** `setText`, `setAttribute`, `setValue`, `addClass`, `removeClass`, `toggleClass`, `setStyle`
-- **Manipulate:** `insertHTML`, `removeElement`, `clickElement`
+- **Manipulate:** `insertHTML`, `removeElement`, `clickElement`, `scrollIntoView`
 - **Forms:** `getFormData`, `startFormClickListener`, `stopFormClickListener`, `setFormFieldValue`
 - **Element Injection:** `injectElement`, `removeInjectedElement`
 - **Element Listeners:** `startElementClickListener`, `stopElementClickListener`