@ray-js/robot-map-sdk 0.0.11 → 0.0.12

package/bin/docs-server.js

@@ -3,6 +3,7 @@
 import { createServer } from 'node:http'
 import { readFile, stat } from 'node:fs/promises'
 import { dirname, extname, join, normalize } from 'node:path'
+import { spawn } from 'node:child_process'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
@@ -26,17 +27,24 @@ const MIME_TYPES = {
 
 const HELP_TEXT = `
 Usage:
-  robot-map-docs [--host <host>] [--port <port>]
+  robot-map-docs [--host <host>] [--port <port>] [--open]
 
 Options:
   --host, -H    Host to bind (default: 127.0.0.1)
-  --port, -p    Port to listen on (default: 4173)
+  --port, -p    Port to listen on (default: 5180)
+  --open, -o    Open docs in browser after server starts
+  --no-open     Disable browser auto-open
+  --quiet, -q   Minimal logs (errors only)
   --help, -h    Show this help message
 `
 
 const parseArgs = (argv) => {
   let host = '127.0.0.1'
-  let port = 4173
+  let port = 5180
+  let shouldOpen =
+    process.env.ROBOT_MAP_DOCS_OPEN === '1' ||
+    process.env.ROBOT_MAP_DOCS_OPEN === 'true'
+  let quiet = false
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
@@ -62,9 +70,24 @@ const parseArgs = (argv) => {
       i += 1
       continue
     }
+
+    if (arg === '--open' || arg === '-o') {
+      shouldOpen = true
+      continue
+    }
+
+    if (arg === '--no-open') {
+      shouldOpen = false
+      continue
+    }
+
+    if (arg === '--quiet' || arg === '-q') {
+      quiet = true
+      continue
+    }
   }
 
-  return { host, port }
+  return { host, port, shouldOpen, quiet }
 }
 
 const getSafePath = (rawPathname) => {
@@ -86,6 +109,104 @@ const getSafePath = (rawPathname) => {
 const currentFile = fileURLToPath(import.meta.url)
 const currentDir = dirname(currentFile)
 const docsRoot = join(currentDir, '..', 'dist-docs')
+const packageRoot = join(currentDir, '..')
+
+const isColorEnabled = () =>
+  process.stdout.isTTY &&
+  process.env.NO_COLOR !== '1' &&
+  process.env.FORCE_COLOR !== '0'
+
+const color = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  accent: '\x1b[38;2;72;151;108m',
+  accentSoft: '\x1b[38;2;121;206;160m',
+  warn: '\x1b[38;2;214;162;64m',
+  danger: '\x1b[38;2;220;95;95m',
+  bold: '\x1b[1m',
+}
+
+const withColor = (value, style) => {
+  if (!isColorEnabled()) return value
+  return `${style}${value}${color.reset}`
+}
+
+const createLogger = ({ quiet }) => ({
+  info: (text) => {
+    if (!quiet) {
+      console.log(`${withColor('[docs]', color.accent)} ${text}`)
+    }
+  },
+  warn: (text) => {
+    if (!quiet) {
+      console.warn(`${withColor('[warn]', color.warn)} ${text}`)
+    }
+  },
+  error: (text) => {
+    console.error(`${withColor('[error]', color.danger)} ${text}`)
+  },
+})
+
+const formatDurationMs = (durationMs) => `${Math.max(0, durationMs)}ms`
+
+const formatBorder = (title) =>
+  withColor(`+-------------------- ${title} --------------------+`, color.accent)
+
+const renderBanner = ({ version, host, port, startupMs, openMode }) => {
+  const endpoint = `http://${host}:${String(port)}`
+  const lines = [
+    formatBorder('Robot Map Docs'),
+    `${withColor('  Package  ', color.dim)} ${withColor(
+      `@ray-js/robot-map-sdk@${version}`,
+      color.bold,
+    )}`,
+    `${withColor('  URL      ', color.dim)} ${withColor(endpoint, color.accentSoft)}`,
+    `${withColor('  Open     ', color.dim)} ${openMode}`,
+    `${withColor('  Startup  ', color.dim)} ${formatDurationMs(startupMs)}`,
+    withColor('+---------------------------------------------------+', color.accent),
+    withColor('Press Ctrl+C to stop', color.dim),
+  ]
+  return lines.join('\n')
+}
+
+const getPackageVersion = async () => {
+  try {
+    const content = await readFile(join(packageRoot, 'package.json'), 'utf-8')
+    const parsed = JSON.parse(content)
+    if (typeof parsed.version === 'string' && parsed.version.trim()) {
+      return parsed.version
+    }
+  } catch (_error) {
+    // Ignore and fall back to unknown.
+  }
+  return 'unknown'
+}
+
+const openBrowser = (url) => {
+  let cmd = ''
+  let args = []
+
+  if (process.platform === 'darwin') {
+    cmd = 'open'
+    args = [url]
+  } else if (process.platform === 'win32') {
+    cmd = 'cmd'
+    args = ['/c', 'start', '', url]
+  } else {
+    cmd = 'xdg-open'
+    args = [url]
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: 'ignore',
+    })
+    child.on('error', reject)
+    child.unref()
+    resolve()
+  })
+}
 
 const serveFile = async (filePath, response) => {
   const content = await readFile(filePath)
@@ -155,7 +276,10 @@ const createRequestHandler = () => async (request, response) => {
 }
 
 const main = async () => {
-  const { host, port } = parseArgs(process.argv.slice(2))
+  const startTime = Date.now()
+  const { host, port, shouldOpen, quiet } = parseArgs(process.argv.slice(2))
+  const logger = createLogger({ quiet })
+  const packageVersion = await getPackageVersion()
 
   try {
     const rootStat = await stat(docsRoot)
@@ -169,22 +293,82 @@ const main = async () => {
           ? error.code
           : undefined
       if (String(maybeCode ?? '') !== 'ENOENT') {
-        console.warn(
-          `[robot-map-docs] docs root check warning: ${error.message}`,
-        )
+        logger.warn(`docs root check warning: ${error.message}`)
       }
     }
-    console.error(
-      '[robot-map-docs] dist-docs not found. Please build docs before publish.',
-    )
+    logger.error('dist-docs not found. Please build docs before publish.')
     process.exit(1)
   }
 
   const server = createServer(createRequestHandler())
+  const sockets = new Set()
+  let shuttingDown = false
+
+  server.on('connection', (socket) => {
+    sockets.add(socket)
+    socket.on('close', () => {
+      sockets.delete(socket)
+    })
+  })
+
+  server.on('error', (error) => {
+    const message = error instanceof Error ? error.message : String(error)
+    logger.error(`failed to start server: ${message}`)
+    if (String((error && error.code) ?? '') === 'EADDRINUSE') {
+      logger.warn(`port ${port} is already in use. Try "--port ${port + 1}".`)
+    }
+    process.exit(1)
+  })
+
   server.listen(port, host, () => {
-    console.log(
-      `[robot-map-docs] Serving dist-docs at http://${host}:${String(port)}`,
-    )
+    const endpoint = `http://${host}:${String(port)}`
+    const startupMs = Date.now() - startTime
+    if (!quiet) {
+      console.log(
+        renderBanner({
+          version: packageVersion,
+          host,
+          port,
+          startupMs,
+          openMode: shouldOpen ? 'enabled' : 'disabled',
+        }),
+      )
+    } else {
+      logger.info(`serving dist-docs at ${endpoint}`)
+    }
+
+    if (shouldOpen) {
+      openBrowser(endpoint).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`failed to open browser automatically: ${message}`)
+      })
+    }
+  })
+
+  process.once('SIGINT', () => {
+    if (shuttingDown) {
+      logger.warn('force exit on repeated interrupt')
+      process.exit(130)
+    }
+
+    shuttingDown = true
+    logger.info('shutting down...')
+
+    server.close()
+
+    for (const socket of sockets) {
+      socket.destroy()
+    }
+
+    // Always terminate quickly in CLI usage; do not risk hanging on keep-alive.
+    setTimeout(() => {
+      process.exit(130)
+    }, 80)
+
+    setTimeout(() => {
+      logger.warn('shutdown timeout, forcing exit')
+      process.exit(130)
+    }, 1500).unref()
   })
 }
 

package/dist-docs/404.html

@@ -9,14 +9,14 @@
     <link rel="preload stylesheet" href="/assets/style.DrlDtCux.css" as="style">
     <link rel="preload stylesheet" href="/vp-icons.css" as="style">
     
-    <script type="module" src="/assets/app.3-ianRvb.js"></script>
+    <script type="module" src="/assets/app.Bg6Ypeoa.js"></script>
     <link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"COVLyRkA\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"DzTPTYGC\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"records_bugs_2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md\":\"BbQpA41Y\",\"records_bugs_2026-03-10-events-drawer-toolbar-scroll-bugfix.md\":\"DbHxPv4D\",\"records_bugs_2026-03-10-simulator-initial-render-layout-bugfix.md\":\"w7--2hvH\",\"records_bugs_2026-03-10-simulator-wheel-scroll-leak-bugfix.md\":\"B6gIem2P\",\"records_bugs_2026-03-11-docs-server-bin-clean-bugfix.md\":\"GGWCjkok\",\"records_plans_2026-03-02-furniture-feature-plan.md\":\"CqSsyNDo\",\"records_plans_2026-03-10-simulator-events-console-plan.md\":\"CfHLEHcc\",\"records_plans_2026-03-10-simulator-last-successful-combo-cache-plan.md\":\"Z2RoK239\",\"records_plans_2026-03-10-simulator-map-parsed-view-plan.md\":\"S9jPz75o\",\"records_plans_2026-03-10-simulator-map-playground-refactor-plan.md\":\"BuILlmcV\",\"records_plans_2026-03-10-simulator-playground-plan.md\":\"CQAR-T7p\",\"records_plans_2026-03-10-simulator-runtime-controls-plan.md\":\"DSVD-qCa\",\"records_plans_2026-03-11-simulator-src-migration-implementation.md\":\"FnB5Cx6R\",\"records_plans_2026-03-11-simulator-src-migration-plan.md\":\"BBfaeRrq\",\"reference_callbacks.md\":\"BIwuGR3s\",\"reference_config.md\":\"DHynhVxG\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"eH-UCMbE\",\"reference_runtime.md\":\"BEy8BhSZ\",\"reference_types.md\":\"hikiO8Cq\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_advanced-usage.md\":\"COVLyRkA\",\"guide_concepts.md\":\"CJ87tk-r\",\"guide_getting-started.md\":\"D2j6CRj3\",\"guide_mcp.md\":\"CabCiX8Z\",\"index.md\":\"wTsFvv0N\",\"plans_2026-03-04-detected-objects-visibility-design.md\":\"Dqboot5W\",\"plans_2026-03-04-show-detected-objects-implementation-plan.md\":\"CDWwQtWj\",\"plans_2026-03-10-simulator-debug-design.md\":\"BZibn7uw\",\"plans_2026-03-10-simulator-events-console-design.md\":\"BVmEzCbR\",\"plans_2026-03-10-simulator-events-console-implementation-plan.md\":\"S2f1zs9-\",\"plans_2026-03-10-simulator-runtime-controls-design.md\":\"mqeNaYgg\",\"plans_2026-03-10-simulator-runtime-controls-implementation-plan.md\":\"BXG1UWFt\",\"records_bugs_2026-02-28-fix-pixi-bindgroup-webgpu-snapshot-whitescreen-bugfix.md\":\"BbQpA41Y\",\"records_bugs_2026-03-10-events-drawer-toolbar-scroll-bugfix.md\":\"DbHxPv4D\",\"records_bugs_2026-03-10-simulator-initial-render-layout-bugfix.md\":\"w7--2hvH\",\"records_bugs_2026-03-10-simulator-wheel-scroll-leak-bugfix.md\":\"B6gIem2P\",\"records_bugs_2026-03-11-docs-server-bin-clean-bugfix.md\":\"GGWCjkok\",\"records_plans_2026-03-02-furniture-feature-plan.md\":\"CqSsyNDo\",\"records_plans_2026-03-10-simulator-events-console-plan.md\":\"CfHLEHcc\",\"records_plans_2026-03-10-simulator-last-successful-combo-cache-plan.md\":\"Z2RoK239\",\"records_plans_2026-03-10-simulator-map-parsed-view-plan.md\":\"S9jPz75o\",\"records_plans_2026-03-10-simulator-map-playground-refactor-plan.md\":\"BuILlmcV\",\"records_plans_2026-03-10-simulator-playground-plan.md\":\"CQAR-T7p\",\"records_plans_2026-03-10-simulator-runtime-controls-plan.md\":\"DSVD-qCa\",\"records_plans_2026-03-11-docs-cli-ui-polish-plan.md\":\"B8oZt_5R\",\"records_plans_2026-03-11-simulator-src-migration-implementation.md\":\"FnB5Cx6R\",\"records_plans_2026-03-11-simulator-src-migration-plan.md\":\"BBfaeRrq\",\"reference_callbacks.md\":\"BIwuGR3s\",\"reference_config.md\":\"DHynhVxG\",\"reference_data.md\":\"B_XpUFrn\",\"reference_methods.md\":\"eH-UCMbE\",\"reference_runtime.md\":\"BEy8BhSZ\",\"reference_types.md\":\"hikiO8Cq\",\"reference_utils.md\":\"Dy6XKVWh\",\"simulator_index.md\":\"CF95Y_c9\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Tuya Robot Map\",\"description\":\"涂鸦扫地机地图组件\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"siteTitle\":\"Tuya Robot Map\",\"outline\":{\"level\":[2,6],\"label\":\"页面导航\"},\"nav\":[{\"text\":\"首页\",\"link\":\"/\"},{\"text\":\"指南\",\"link\":\"/guide/concepts\",\"activeMatch\":\"^/guide/\"},{\"text\":\"参考\",\"link\":\"/reference/data\",\"activeMatch\":\"^/reference/\"},{\"text\":\"模拟调试\",\"link\":\"/simulator/\",\"activeMatch\":\"^/simulator/\"}],\"sidebar\":{\"/guide/\":[{\"text\":\"指南\",\"items\":[{\"text\":\"基本概念\",\"link\":\"/guide/concepts\"},{\"text\":\"快速开始\",\"link\":\"/guide/getting-started\"},{\"text\":\"进阶使用\",\"link\":\"/guide/advanced-usage\"}]}],\"/reference/\":[{\"text\":\"组件Props\",\"items\":[{\"text\":\"数据\",\"link\":\"/reference/data\"},{\"text\":\"配置\",\"link\":\"/reference/config\"},{\"text\":\"运行时\",\"link\":\"/reference/runtime\"},{\"text\":\"地图事件回调\",\"link\":\"/reference/callbacks\"}]},{\"text\":\"方法\",\"items\":[{\"text\":\"地图方法\",\"link\":\"/reference/methods\"},{\"text\":\"工具方法\",\"link\":\"/reference/utils\"}]},{\"text\":\"类型定义\",\"items\":[{\"text\":\"类型定义\",\"link\":\"/reference/types\"}]}],\"/simulator/\":[{\"text\":\"模拟调试\",\"items\":[{\"text\":\"实时模拟调试\",\"link\":\"/simulator/\"}]}]},\"search\":{\"provider\":\"local\"},\"lastUpdated\":{\"text\":\"最后更新于\",\"formatOptions\":{\"dateStyle\":\"short\",\"timeStyle\":\"short\"}}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist-docs/assets/{app.3-ianRvb.js → app.Bg6Ypeoa.js}

@@ -1 +1 @@
-import{R as p}from"./chunks/theme.Dn4kNa0x.js";import{R as s,ad as i,ae as u,af as c,ag as l,ah as f,ai as d,aj as m,ak as h,al as g,am as A,d as v,u as R,v as w,s as y,an as C,ao as P,ap as b,a7 as E}from"./chunks/framework.CBLqO2Q1.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
+import{R as p}from"./chunks/theme.CKxbjNbw.js";import{R as s,ad as i,ae as u,af as c,ag as l,ah as f,ai as d,aj as m,ak as h,al as g,am as A,d as v,u as R,v as w,s as y,an as C,ao as P,ap as b,a7 as E}from"./chunks/framework.CBLqO2Q1.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};